README

Contentful Pipelines

How to Install

npm -D install @xolvio/contentful-pipelines

API

The contentful pipelines package exposes two commands which can be run either as a package.json script or executed in the code (runtime).

Migrations

Given directory structure:

your-project
├── README.md
├── src
│   └── components
│       ├── Title
│       │    └── migrations
│       │         └── title
│       │               └── 1513695986378-create-title-type.js
│       └── Sections
│            └── migrations
│                 └── sections
│                       └── 1513695986378-create-title-type.js
├── package.json

Running as package.json command:

"migrations": "CONTENTFUL_MANAGEMENT_API=<contentful-management-api-key> CONTENTFUL_SPACE_ID=<contentful-space-id> CONTENTFUL_ENVIRONMENT_ID=<contentful-environment-id> xolvio-contentful-migrations src/components/Title src/components/Sections"

Running from code:

async function runMigrations(migrationPaths, options);

Parameter	Type	Default	Description
`migrationPaths`	`string[]`	[]	Required. List of paths to the components containing migration scripts. Paths should be relative to the project's root.
`options`	{ targetEnvironment: `string`, spaceId: `string`, contentfulManagementApiKey: `string` }	`targetEnvironment = process.env.CONTENTFUL_ENVIRONMENT_ID` `spaceId = process.env.CONTENTFUL_SPACE_ID` `contentfulManagementApiKey = process.env.CONTENTFUL_MANAGEMENT_API`	Optional. Overwrites the `process.env` variables

const { runMigrations } = require("@xolvio/contentful-pipelines");

await runMigrations(["src/components/Title", "src/components/Sections"]);

Creating the contentful environment

Running as package.json command:

"createQaEnvironmentFromProd": "CONTENTFUL_MANAGEMENT_API=<contentful-management-api-key> CONTENTFUL_SPACE_ID=<contentful-space-id> CONTENTFUL_SOURCE_ENVIRONMENT=<contentful-prod-environment-id> CONTENTFUL_ENVIRONMENT_ID=<contentful-environment-id> xolvio-contentful-create-environment"

Running from code:

async function createEnvironmentFromSource(options);

Parameter	Type	Default	Description
`options`	{ sourceEnvironment: `string`, targetEnvironment: `string`, spaceId: `string`, contentfulManagementApiKey: `string` }	`sourceEnvironment=process.env.CONTENTFUL_SOURCE_ENVIRONMENT` `targetEnvironment = process.env.CONTENTFUL_ENVIRONMENT_ID` `spaceId = process.env.CONTENTFUL_SPACE_ID` `contentfulManagementApiKey = process.env.CONTENTFUL_MANAGEMENT_API`	Optional. Overwrites the `process.env` variables

Example:

await createEnvironmentFromSource();

Writing migration scripts

For executing the migrations we're using Contentful Migrate Tool so the migrations are written using their syntax. Using their CLI tool you can quickly create the migration scripts based on the existing Contentful Content Types.

Useful scripts

Fetch existing entry data (used for initial data migration scripts)

module.exports.up = async (migration, { makeRequest }) => {
  const existing = await makeRequest({
    method: "GET",
    url: `/entries/ENTRY_ID_TO_QUERY`,
  }).catch(console.log);

  console.log("existing: ", JSON.stringify(existing.fields));
};

Create contentful entry from within the contentful migration script:

module.exports.up = async (migration, { makeRequest }) => {
  await makeRequest({
    method: "PUT",
    url: `/entries/NEW_ENTRY_ID`,
    data: EXISTING_FIELDS_FROM_SNIPPET_ABOVE,
    headers: {
      "X-Contentful-Content-Type": "CONTENT_TYPE_ID",
    },
  });
};

TODO

CLI for running migrations for all of the components listed in the package.json

Usage no npm install needed!