Registry / devops / contentful-migration-tool

contentful-migration-tool

library1.3.0jsnpmunverified

A CLI and Docker tool that simplifies running Contentful migrations with a single command. Current stable version is 1.3.0. It wraps the official contentful-migration package, adding a runner that tracks executed migrations and supports TypeScript via tsx. Provides environment variable configuration for Content Management Token, Space ID, and Environment ID. Designed for CI/CD integration (e.g., CircleCI) as an alternative to manual migration orchestration.

devops

npm install contentful-migration-tool

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-MIGRATI

contentful-migration-tool

devopsjavascriptv1.3.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.

contentful-migration-tool

✓ npx -p contentful-migration@latest -p contentful-migration-tool@latest contentful-migration-tool run ./migrations

✗ npm i -g contentful-migration-tool

CLI tool; package is not imported but used as a command. Must be invoked with npx or installed as devDependency

docker run

✓ docker run --rm --tty --name contentful-migration-runner -e CONTENT_MANAGEMENT_TOKEN=$CONTENT_MANAGEMENT_TOKEN -e SPACE_ID=$SPACE_ID -e ENVIRONMENT_ID=$ENVIRONMENT_ID -v $(pwd)/migrations:/app/migrations marcomontalbano/contentful-migration

✗ docker run marcomontalbano/contentful-migration

Docker usage requires mounting migrations folder and setting environment variables

Installs dependencies, sets environment variables, creates a migration file, and runs migrations

npm install --save-dev contentful-migration@latest contentful-migration-tool@latest export CONTENT_MANAGEMENT_TOKEN='<your_token>' export SPACE_ID='<your_space_id>' export ENVIRONMENT_ID='<your_environment_id>' mkdir -p migrations # create a migration file e.g. migrations/01-create-blog-post.js cat << 'EOF' > migrations/01-create-blog-post.js module.exports = function (migration) { const blogPost = migration.createContentType('blogPost') .name('Blog Post') .description('A blog post') .displayField('title'); blogPost.createField('title') .name('Title') .type('Symbol') .required(true); }; EOF npx contentful-migration-tool run ./migrations

Debug

Known issues

breakingNode.js >=18 required (engines field). Older Node versions will fail to run the tool.

fix

Upgrade Node.js to version 18 or later.

affects: >=1.0.0

gotchaTypeScript migrations require tsx to be installed separately; the CLI does not include TypeScript support by default.

fix

Install tsx as a devDependency: npm install --save-dev tsx, then run with npx tsx ./node_modules/.bin/contentful-migration-tool run ./migrations

affects: >=1.0.0

gotchaThe contentful-migration package is a peer dependency; it must be installed alongside contentful-migration-tool.

fix

Install contentful-migration as a devDependency: npm install --save-dev contentful-migration

affects: >=1.0.0

gotchaEnvironment variables CONTENT_MANAGEMENT_TOKEN, SPACE_ID, and ENVIRONMENT_ID are required. Missing any will cause the command to fail with no clear error.

fix

Ensure all three environment variables are set before running the command.

affects: >=1.0.0

gotchaDocker volume mount path must be /app/migrations; using a different path will cause the container to not find migration files.

fix

Mount your migrations folder to /app/migrations using -v $(pwd)/migrations:/app/migrations

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'contentful-migration'

Peer dependency contentful-migration not installed.

fix

Run npm install --save-dev contentful-migration@latest

Error: Migration file not found: ./migrations

Migrations directory does not exist or path is incorrect.

fix

Ensure the migrations directory exists and contains .js or .ts files. Run mkdir -p migrations.

Error: connect ECONNREFUSED 127.0.0.1:443

Contentful API endpoint not reachable, often due to missing or invalid environment variables.

fix

Verify that CONTENT_MANAGEMENT_TOKEN, SPACE_ID, and ENVIRONMENT_ID are correctly set.

SyntaxError: Cannot use import statement outside a module

Migration file uses ES modules but tsx is not used for TypeScript or node does not support ESM.

fix

Use CommonJS syntax (module.exports) or run with tsx: npx tsx ./node_modules/.bin/contentful-migration-tool run ./migrations

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

contentful-migrationrequiredPeer dependency required to run migrations

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/marcomontalbano/contentful-migration-tool ↗

packagecontentful-migration-tool ↗

homepagehttps://github.com/marcomontalbano/contentful-migration-tool#readme ↗