Contentful Migration Tooling

Contentful Migration validates your script to ensure actions on content types and fields are logically sound. Error keys are scoped using a specific pattern based on the entity and the action being performed:

{entity}.{action}.{validation_name}

For example, an error occurring during a field creation might look like field.create.FIELD_ALREADY_CREATED.

Some validation errors are scoped only to the entity itself (e.g., {entity}.{validation_name}) when they relate to the final payload generated after the migration script is evaluated.

The project supports three distinct release channels to manage stable and pre-release software:

• main: The stable release branch (latest).
• beta: A pre-release branch for testing.
• dev: A pre-release branch for development.

Merging code into these branches triggers the automated publishing process for the respective channel.

The contentful-migration package serves as the core migration engine and Domain Specific Language (DSL) library. While it contains a bin/contentful-migration entry point for backward compatibility and testing, it is no longer the recommended user-facing CLI tool.

Instead, contentful-cli acts as the primary interface for users, consuming contentful-migration as a dependency to provide the space migration command. Developers building custom migration scripts should use contentful-migration as a library rather than relying on the standalone CLI binary.

To write effective migration scripts, understand these core abstractions:

• Migration Script: A JS/TS file that exports a function receiving the migration object.
• Intent: An internal representation of a single discrete operation (e.g., "create content type X").
• Request Batch: A group of HTTP requests belonging to a single intent, executed sequentially.
• Offline API: An in-memory simulation of the CMA state used to validate your migration plan locally before any real API calls are made.
• Context: An object passed to migration scripts containing makeRequest, spaceId, and accessToken, allowing for "escape-hatch" direct CMA access if the DSL is insufficient.

The release process relies on specific commit message patterns to determine the next version bump:

• Major bump: Triggered by breaking changes. Use the feat!: syntax or include a BREAKING CHANGE: footer in the commit message.
• Patch bump: Triggered by dependency updates, such as using the build(deps) prefix.
• Changelog generation: Automated via @semantic-release/changelog based on commit history.

The project uses semantic-release to automate the release lifecycle. Version numbers are derived from commit messages, changelogs are generated automatically, and packages are published to npm without manual intervention.

To ensure correct versioning, developers must follow the Conventional Commits specification. The version field in package.json is kept at 0.0.0-development, as semantic-release manages the actual published version numbers.

The migration API supports two styles of method calls:

1. Chained approach (Recommended): Allows for better error reporting. Validation errors will display the specific line number where the error occurred.
2. Object approach: Uses a single configuration object. Validation errors will only point to the line where the object is defined, making debugging harder.

Example of Chaining:

const author = migration
  .createContentType('author')
  .name('Author')
  .description('Author of blog posts or pages')

Example of Object notation:

const author = migration.createContentType('author', {
  name: 'Author',
  description: 'Author of blog posts or pages'
})

To delete a field, you must first mark it as omitted. Using .deleted(true) on a field that hasn't been omitted first will trigger a field.NO_DELETE_WITHOUT_OMIT error.

Recommendation: Use the deleteField shorthand method to perform both operations (omitting and deleting) in a single step.

// Error: field.NO_DELETE_WITHOUT_OMIT
const author = migration.editContentType('author')
author.editField('fullName').deleted(true)

// Correct way (manual):
author.editField('fullName').omitted(true).deleted(true)

// Correct way (shorthand):
// migration.deleteField('author', 'fullName')

To add or update integration tests, set the NOCK_RECORD environment variable to 1. This will automatically update the recorded fixtures.

NOCK_RECORD=1

When upgrading to contentful-migration v5.0.0, you must ensure that your environment meets the following dependency requirements:

• contentful-management SDK: You must use version v12 or higher.
• Library Consumers: If you are using contentful-migration as a library in your own code, you must manually update your contentful-management peer dependency to v12+ to avoid compatibility issues.
• CLI Users: If you use contentful-cli, upgrading to contentful-cli v4.0.0 will automatically provide contentful-migration v5.0.0.