Registry / devops / contentful-migration-helper

contentful-migration-helper

library1.2.1jsnpmunverified

A CLI tool and library for managing Contentful content model migrations. Version 1.2.1 provides a structured way to create, update, and delete content types and fields using JavaScript/TypeScript migration files. It clones a source environment (typically master), applies migrations, and can update aliases. Compared to raw Contentful Migration, this helper offers a higher-level API with environment cloning, confirmation prompts, and delete/alias commands. The package is stable with weekly releases on npm.

devops

npm install contentful-migration-helper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-MIGRATI

contentful-migration-helper

devopsjavascriptv1.2.1

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.

default

✓ const migrationHelper = require('contentful-migration-helper');

✗ import migrationHelper from 'contentful-migration-helper';

This package uses CommonJS; ESM import will fail.

config

✓ const config = require('./contentful-migration-tool.config.js');

Configuration file is required and must export an object with spaceId, managementToken, and migrationDirectory.

Sets up config file and a sample migration to create a content type with a title field.

// contentful-migration-tool.config.js module.exports = { spaceId: process.env.CONTENTFUL_SPACE_ID ?? '', managementToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN ?? '', migrationDirectory: './migrations', }; // migrations/1.create-test-type.js export = function (migration) { const testType = migration.createContentType('testType').name('Test Type'); testType.createField('title').type('Symbol').name('Title').required(true); testType.displayField('title'); };

Debug

Known issues

breakingCLI command changed from `contentful` to `contentful-migration-helper` in v1.0.0

fix

Use `yarn contentful-migration-helper migrate` instead of `yarn contentful migrate`.

affects: <1.0.0

deprecatedThe `update-alias` command may be removed in future versions

fix

Use Contentful Management API directly for alias updates.

affects: >=1.0.0

gotchaMigration files must be CommonJS (module.exports) not ESM; TypeScript requires ts-node

fix

Write migration files with `export = function (migration) {...}`. For TypeScript, run via ts-node.

affects: >=1.0.0

gotchaEnvironment deletion is irreversible; the `--skip` flag bypasses prompts

fix

Always review environment names before using `--skip`.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'contentful-migration-helper'

Package not installed or installed globally instead of locally

fix

Run `npm install contentful-migration-helper` in your project directory.

Error: No configuration file found

Missing or misnamed contentful-migration-tool.config.js

fix

Create the config file in the root of your project with correct exports.

TypeError: migration.createContentType is not a function

Migration function signature mismatch; parameter is not the migration object

fix

Ensure the export is `export = function (migration) {...}` (CommonJS) and the parameter name is correct.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

contentful-migrationrequiredCore dependency for running Contentful migrations

contentful-managementrequiredContentful Management SDK for environment operations

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/pnarielwala/contentful_scripts ↗

packagecontentful-migration-helper ↗

homepagehttps://github.com/pnarielwala/contentful_scripts#readme ↗