Registry / devops / contentful-migrate

contentful-migrate

library0.17.0jsnpmunverified

A command-line migration tool for Contentful, version 0.17.0, that manages content type schema changes through incremental scripted files based on the CMS as Code approach. It tracks the state of each content type in a 'Migration' content type within the space, ensuring idempotent and reversible migrations. Key differentiators: supports up/down migrations, per-content-type subdirectories, and integration with Contentful's migration library.

devops

npm install contentful-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-MIGRATE

contentful-migrate

devopsjavascriptv0.17.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ctf-migrate

✓ npx ctf-migrate [command]

✗ require('contentful-migrate')

CLI tool, not a programmatic library; use npx or global install.

Initialize Contentful space for migrations, create a new migration script for a 'post' content type, then apply it.

mkdir my-project && cd my-project npm init -y npx contentful-migrate init --access-token $CONTENTFUL_MANAGEMENT_ACCESS_TOKEN --space-id $CONTENTFUL_SPACE_ID npx contentful-migrate create --name 'Create Post Model' --content-type post # Edit migrations/post/<timestamp>-create-post-model.js with migration script npx contentful-migrate up --content-type post

Debug

Known issues

gotchaMigrations directory must be inside the project root; placing it outside version control can cause out-of-sync issues.

fix

Ensure CONTENTFUL_MIGRATION_DIR points to a git-tracked folder under the project.

affects: >=0.1.0

breakingcontentful-migration peer dependency version may break with newer major releases; check compatibility.

fix

Install compatible contentful-migration version (see package.json peerDependencies).

affects: >=0.17.0

deprecatedEnvironment variable CONTENTFUL_MIGRATION_DIR is used; future versions may change configuration approach.

fix

Use CONTENTFUL_MIGRATION_DIR or watch for breaking changes in config.

affects: <=0.17.0

gotchaWhen initializing an already initialized space, error 'Content type with id migration already exists' occurs.

fix

Run 'ctf-migrate init' only once per space/environment.

affects: >=0.1.0

gotchaPersonal access token required for all commands; missing token causes authentication errors.

fix

Set CONTENTFUL_MANAGEMENT_ACCESS_TOKEN environment variable or pass --access-token.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Content type with id "migration" already exists.

Attempting to run init on a space that already has a Migration content type.

fix

Do not run init again; use 'ctf-migrate status' to see existing state.

Error: ENOENT: no such file or directory, open 'migrations/...'

Migrations folder structure is missing or misconfigured.

fix

Create the migrations directory structure matching expected content type subfolders, or set CONTENTFUL_MIGRATION_DIR correctly.

Error: Invalid access token

Missing or incorrect CMA token.

fix

Ensure CONTENTFUL_MANAGEMENT_ACCESS_TOKEN is set and valid.

Error: contentful-migration version mismatch

Incompatible contentful-migration peer dependency.

fix

Install the correct contentful-migration version (e.g., npm install contentful-migration@peerVersion).

Upgrade

Version history

0.17.0latest on npm

Audit

Dependencies

contentful-migrationrequiredCore migration syntax and execution

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/deluan/contentful-migrate ↗

packagecontentful-migrate ↗

homepagehttps://github.com/deluan/contentful-migrate#readme ↗