{"id":47302,"library":"contentful-cli-migrations","title":"Contentful CLI Migrations","description":"Contentful CLI Migrations is an open-source CLI tool and library for automating Contentful space migrations. Version 1.0.0, released in 2025, provides a command-line interface to define, version, and apply migration scripts using a counter entry in Contentful to track progress. It relies on contentful-management and contentful-migration as peer dependencies, and requires Node.js >=22. Unlike the official Contentful Migration CLI, this tool enforces a specific file naming convention (e.g., 0001-migration.cjs) and integrates a counter entry pattern for tracking migration state. It is designed for CI/CD workflows and supports JavaScript/CommonJS migration scripts.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/AtidaTech/contentful-cli-migrations","tags":["javascript","cli","contentful","contentful-export","contentful-cli","contentful-cli-migrations","contentful-migration","contentful-migrations","migration"],"install":[{"cmd":"npm install contentful-cli-migrations","lang":"bash","label":"npm"},{"cmd":"yarn add contentful-cli-migrations","lang":"bash","label":"yarn"},{"cmd":"pnpm add contentful-cli-migrations","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to interact with the Contentful Management API for applying migrations.","package":"contentful-management","optional":false},{"reason":"Core migration engine used to define and run migration steps.","package":"contentful-migration","optional":false},{"reason":"Utility library for Contentful operations, required as a peer dependency.","package":"contentful-lib-helpers","optional":false}],"imports":[{"note":"Only ESM imports are supported; this package does not export a CommonJS version.","wrong":"const runMigrations = require('contentful-cli-migrations')","symbol":"runMigrations","correct":"import { runMigrations } from 'contentful-cli-migrations'"},{"note":"getMigrationStatus is a named export, not a default export.","wrong":"import getMigrationStatus from 'contentful-cli-migrations'","symbol":"getMigrationStatus","correct":"import { getMigrationStatus } from 'contentful-cli-migrations'"},{"note":"MigrationConfig is a TypeScript interface, only available as a type import.","wrong":"import { MigrationConfig } from 'contentful-cli-migrations'","symbol":"MigrationConfig","correct":"import type { MigrationConfig } from 'contentful-cli-migrations'"}],"quickstart":{"code":"import { runMigrations } from 'contentful-cli-migrations';\n\nconst config = {\n  accessToken: process.env.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN ?? '',\n  spaceId: process.env.CONTENTFUL_SPACE_ID ?? '',\n  environmentId: process.env.CONTENTFUL_ENVIRONMENT_ID ?? 'master',\n  migrationsDir: './migrations/scripts',\n  counterEntryId: 'COUNTER_ENTRY_ID',\n  counterFieldId: 'migrationCounter',\n};\n\nasync function migrate() {\n  try {\n    const result = await runMigrations(config);\n    console.log('Migrations applied:', result);\n  } catch (error) {\n    console.error('Migration failed:', error);\n    process.exit(1);\n  }\n}\n\nmigrate();","lang":"typescript","description":"Shows how to import and run the migration function with environment variables for authentication."},"warnings":[{"fix":"Upgrade Node.js to >=22.","message":"Node.js version 22 or higher is required. Older versions will fail with syntax errors due to ESM features.","severity":"breaking","affected_versions":"<22.0.0"},{"fix":"Ensure migration files follow the convention: <digits>-<name>.cjs or .js.","message":"Migration files must be named with a leading numeric index and a dash (e.g., 0001-my-migration.cjs). Duplicate numbers or missing dashes will cause errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use 'import' syntax. If using CommonJS, you can use dynamic import() in an async function.","message":"The package is ESM-only and cannot be require()'d. Attempting to use CommonJS require() will throw a runtime error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Create a Contentful entry with a field (e.g., integer) to track the last applied migration number.","message":"The counter entry pattern is required; if the counter entry or field is missing, the migration will fail.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'0001-migration.cjs':80 '1.0.0':22 '2025':25 '22':64 'appli':36 'autom':17 'ci/cd':95 'cli':2,5,12,70,103,110,113 'command':29 'command-lin':28 'content':1,4,18,44,52,56,68,104,106,109,112,116,119 'contentful-c':108 'contentful-cli-migr':111 'contentful-export':105 'contentful-manag':51 'contentful-migr':55,115,118 'convent':78 'counter':41,84 'defin':33 'depend':60 'design':93 'e.g':79 'enforc':73 'entri':42,85 'export':107 'file':76 'integr':82 'interfac':31 'javascript':102 'javascript/commonjs':99 'librari':15 'line':30 'manag':53 'migrat':3,6,20,37,57,69,89,100,114,117,120,121 'name':77 'node.js':63 'offici':67 'open':10 'open-sourc':9 'pattern':86 'peer':59 'progress':47 'provid':26 'releas':23 'reli':49 'requir':62 'script':38,101 'sourc':11 'space':19 'specif':75 'state':90 'support':98 'tool':13,72 'track':46,88 'unlik':65 'use':39 'version':21,34 'workflow':96","created_at":"2026-06-07T16:50:49.454613+00:00","updated_at":"2026-06-07T16:50:49.454613+00:00","problems":[{"fix":"Run 'npm install contentful-cli-migrations --save' (or yarn/bun equivalent).","cause":"The package is not installed or installed incorrectly.","error":"Error: Cannot find module 'contentful-cli-migrations'"},{"fix":"Use 'import { runMigrations } from 'contentful-cli-migrations'' instead of default import.","cause":"Importing the package incorrectly (e.g., using default import when it's a named export).","error":"TypeError: runMigrations is not a function"},{"fix":"Ensure all migration files have unique numeric prefixes with consistent leading zeros.","cause":"Two migration files have the same numeric prefix (e.g., 0001-first.cjs and 01-second.cjs).","error":"Error: Migration file naming error - duplicate migration number found"}],"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/AtidaTech/contentful-cli-migrations","github":"https://github.com/AtidaTech/contentful-cli-migrations","docs":null,"changelog":null,"pypi":null,"npm":"contentful-cli-migrations","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}}