Registry / devops / contentful-cli-migrations

contentful-cli-migrations

library1.0.0jsnpmunverified

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.

devops

npm install contentful-cli-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-CLI-MIG

contentful-cli-migrations

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

runMigrations

✓ import { runMigrations } from 'contentful-cli-migrations'

✗ const runMigrations = require('contentful-cli-migrations')

Only ESM imports are supported; this package does not export a CommonJS version.

getMigrationStatus

✓ import { getMigrationStatus } from 'contentful-cli-migrations'

✗ import getMigrationStatus from 'contentful-cli-migrations'

getMigrationStatus is a named export, not a default export.

MigrationConfig

✓ import type { MigrationConfig } from 'contentful-cli-migrations'

✗ import { MigrationConfig } from 'contentful-cli-migrations'

MigrationConfig is a TypeScript interface, only available as a type import.

Shows how to import and run the migration function with environment variables for authentication.

import { runMigrations } from 'contentful-cli-migrations'; const config = { accessToken: process.env.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN ?? '', spaceId: process.env.CONTENTFUL_SPACE_ID ?? '', environmentId: process.env.CONTENTFUL_ENVIRONMENT_ID ?? 'master', migrationsDir: './migrations/scripts', counterEntryId: 'COUNTER_ENTRY_ID', counterFieldId: 'migrationCounter', }; async function migrate() { try { const result = await runMigrations(config); console.log('Migrations applied:', result); } catch (error) { console.error('Migration failed:', error); process.exit(1); } } migrate();

Debug

Known issues

breakingNode.js version 22 or higher is required. Older versions will fail with syntax errors due to ESM features.

fix

Upgrade Node.js to >=22.

affects: <22.0.0

gotchaMigration 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.

fix

Ensure migration files follow the convention: <digits>-<name>.cjs or .js.

affects: >=1.0.0

gotchaThe package is ESM-only and cannot be require()'d. Attempting to use CommonJS require() will throw a runtime error.

fix

Use 'import' syntax. If using CommonJS, you can use dynamic import() in an async function.

affects: >=1.0.0

deprecatedThe counter entry pattern is required; if the counter entry or field is missing, the migration will fail.

fix

Create a Contentful entry with a field (e.g., integer) to track the last applied migration number.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'contentful-cli-migrations'

The package is not installed or installed incorrectly.

fix

Run 'npm install contentful-cli-migrations --save' (or yarn/bun equivalent).

TypeError: runMigrations is not a function

Importing the package incorrectly (e.g., using default import when it's a named export).

fix

Use 'import { runMigrations } from 'contentful-cli-migrations'' instead of default import.

Error: Migration file naming error - duplicate migration number found

Two migration files have the same numeric prefix (e.g., 0001-first.cjs and 01-second.cjs).

fix

Ensure all migration files have unique numeric prefixes with consistent leading zeros.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

contentful-managementrequiredRequired to interact with the Contentful Management API for applying migrations.

contentful-migrationrequiredCore migration engine used to define and run migration steps.

contentful-lib-helpersrequiredUtility library for Contentful operations, required as a peer dependency.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/AtidaTech/contentful-cli-migrations ↗

packagecontentful-cli-migrations ↗

homepagehttps://github.com/AtidaTech/contentful-cli-migrations ↗