{"id":47305,"library":"contentful-migration-tool","title":"Contentful Migration Tool","description":"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.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/marcomontalbano/contentful-migration-tool","tags":["javascript","docker","cli","contentful","migration","migrate","contentful-migration","typescript"],"install":[{"cmd":"npm install contentful-migration-tool","lang":"bash","label":"npm"},{"cmd":"yarn add contentful-migration-tool","lang":"bash","label":"yarn"},{"cmd":"pnpm add contentful-migration-tool","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to run migrations","package":"contentful-migration","optional":false}],"imports":[{"note":"CLI tool; package is not imported but used as a command. Must be invoked with npx or installed as devDependency","wrong":"npm i -g contentful-migration-tool","symbol":"contentful-migration-tool","correct":"npx -p contentful-migration@latest -p contentful-migration-tool@latest contentful-migration-tool run ./migrations"},{"note":"Docker usage requires mounting migrations folder and setting environment variables","wrong":"docker run marcomontalbano/contentful-migration","symbol":"docker run","correct":"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"}],"quickstart":{"code":"npm install --save-dev contentful-migration@latest contentful-migration-tool@latest\nexport CONTENT_MANAGEMENT_TOKEN='<your_token>'\nexport SPACE_ID='<your_space_id>'\nexport ENVIRONMENT_ID='<your_environment_id>'\nmkdir -p migrations\n# create a migration file e.g. migrations/01-create-blog-post.js\ncat << 'EOF' > migrations/01-create-blog-post.js\nmodule.exports = function (migration) {\n  const blogPost = migration.createContentType('blogPost')\n    .name('Blog Post')\n    .description('A blog post')\n    .displayField('title');\n  blogPost.createField('title')\n    .name('Title')\n    .type('Symbol')\n    .required(true);\n};\nEOF\nnpx contentful-migration-tool run ./migrations","lang":"javascript","description":"Installs dependencies, sets environment variables, creates a migration file, and runs migrations"},"warnings":[{"fix":"Upgrade Node.js to version 18 or later.","message":"Node.js >=18 required (engines field). Older Node versions will fail to run the tool.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install tsx as a devDependency: npm install --save-dev tsx, then run with npx tsx ./node_modules/.bin/contentful-migration-tool run ./migrations","message":"TypeScript migrations require tsx to be installed separately; the CLI does not include TypeScript support by default.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install contentful-migration as a devDependency: npm install --save-dev contentful-migration","message":"The contentful-migration package is a peer dependency; it must be installed alongside contentful-migration-tool.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all three environment variables are set before running the command.","message":"Environment variables CONTENT_MANAGEMENT_TOKEN, SPACE_ID, and ENVIRONMENT_ID are required. Missing any will cause the command to fail with no clear error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Mount your migrations folder to /app/migrations using -v $(pwd)/migrations:/app/migrations","message":"Docker volume mount path must be /app/migrations; using a different path will cause the container to not find migration files.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.3.0':22 'ad':31 'altern':64 'ci/cd':58 'circleci':61 'cli':5,71 'command':17 'configur':46 'content':1,12,28,48,72,76 'contentful-migr':27,75 'current':18 'design':56 'docker':7,70 'e.g':60 'environ':44,54 'execut':36 'id':52,55 'integr':59 'javascript':69 'manag':49 'manual':66 'migrat':2,13,29,37,67,73,74,77 'offici':26 'orchestr':68 'packag':30 'provid':43 'run':11 'runner':33 'simplifi':10 'singl':16 'space':51 'stabl':19 'support':39 'token':50 'tool':3,8 'track':35 'tsx':42 'typescript':40,78 'variabl':45 'version':20 'via':41 'wrap':24","created_at":"2026-06-07T16:50:51.148017+00:00","updated_at":"2026-06-07T16:50:51.148017+00:00","problems":[{"fix":"Run npm install --save-dev contentful-migration@latest","cause":"Peer dependency contentful-migration not installed.","error":"Error: Cannot find module 'contentful-migration'"},{"fix":"Ensure the migrations directory exists and contains .js or .ts files. Run mkdir -p migrations.","cause":"Migrations directory does not exist or path is incorrect.","error":"Error: Migration file not found: ./migrations"},{"fix":"Verify that CONTENT_MANAGEMENT_TOKEN, SPACE_ID, and ENVIRONMENT_ID are correctly set.","cause":"Contentful API endpoint not reachable, often due to missing or invalid environment variables.","error":"Error: connect ECONNREFUSED 127.0.0.1:443"},{"fix":"Use CommonJS syntax (module.exports) or run with tsx: npx tsx ./node_modules/.bin/contentful-migration-tool run ./migrations","cause":"Migration file uses ES modules but tsx is not used for TypeScript or node does not support ESM.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/marcomontalbano/contentful-migration-tool#readme","github":"https://github.com/marcomontalbano/contentful-migration-tool","docs":null,"changelog":null,"pypi":null,"npm":"contentful-migration-tool","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}