Registry / devops / contentful-migration

contentful-migration

library5.0.0jsnpmunverified

Contentful Migration is a tool for describing and executing changes to your Contentful content model and transforming entry content. It supports creating, editing, and deleting content types, fields, and tags, as well as performing entry transformations like transformEntries, deriveLinkedEntries, and transformEntriesToType. The current stable version is 5.0.0, which requires Node >=22. It uses semantic versioning and releases frequently. Key differentiators include a declarative migration API, support for both chaining and object notation, and tight integration with the Contentful ecosystem.

devops

npm install contentful-migration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-MIGRATI

contentful-migration

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

migration

✓ import { migration } from 'contentful-migration'

✗ const migration = require('contentful-migration')

ESM-only since v5; must use import syntax. Previously could be imported with require in older versions.

default export (runMigration)

✓ import runMigration from 'contentful-migration'

✗ const runMigration = require('contentful-migration').default

The package has a default export (runMigration) and a named export (migration). Since v5, ESM only; default import is the preferred way for running migrations programmatically.

runMigration

✓ import runMigration from 'contentful-migration'

✗ const { runMigration } = require('contentful-migration')

runMigration is the default export; destructuring with named syntax will not work. Use default import.

types

✓ import type { MigrationFunction } from 'contentful-migration'

TypeScript types are bundled; use import type for type-only imports to avoid runtime issues.

Demonstrates creating a new content type with fields, changing a field control, and transforming entries using a migration function.

import runMigration from 'contentful-migration'; const migrationFunction = (migration, context) => { const book = migration.createContentType('book', { name: 'Book', description: 'A book content type' }); book.createField('title', { name: 'Title', type: 'Symbol', required: true }); book.createField('author', { name: 'Author', type: 'Symbol' }); book.changeFieldControl('title', 'builtin', 'singleLine'); migration.transformEntries({ contentType: 'book', from: ['title'], to: ['author'], transformEntryForLocale: async (fromFields, currentLocale) => { return { author: fromFields.title[currentLocale]?.toUpperCase() ?? '' }; } }); }; runMigration({ migrationFunction, spaceId: process.env.CONTENTFUL_SPACE_ID ?? '', accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN ?? '', environmentId: 'master' }).then(() => console.log('Migration complete')).catch(console.error);

Debug

Known issues

breakingVersion 5.0.0 drops CommonJS support; only ESM is supported. Requires Node >=22.

fix

Update to Node >=22 and use import/export syntax instead of require().

affects: >=5.0.0

breakingThe 'migration' named export is the new API builder; the default export is runMigration. In v4, the default export was the migration function builder directly.

fix

Use import runMigration from 'contentful-migration' for running, or import { migration } for building migration steps.

affects: >=5.0.0

deprecatedThe use of 'context.makeRequest' is deprecated. Use 'context.client' from contentful-management instead.

fix

Access the management client via context.client (provided by contentful-management) rather than using makeRequest.

affects: >=5.0.0

gotchatransformEntries requires an async function for transformEntryForLocale; synchronous functions are not supported.

fix

Ensure the transformEntryForLocale callback returns a Promise (or is declared async).

affects: >=3.0.0

gotchaWhen using runMigration, the migrationFunction parameter must be a plain function (not async if not needed) but it is synchronous for the migration steps; entry transformations can be async.

fix

Do not mark the top-level migration function as async unless you need await inside (which is not recommended).

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/contentful-migration/... not supported.

Package is ESM-only from v5, but you are using require() to import it.

fix

Use import statements or configure your project to support ESM (e.g., set type: module in package.json).

TypeError: migration.createContentType is not a function

You are using the default export (runMigration) instead of the named export migration for building migration steps.

fix

Use import { migration } from 'contentful-migration' to access the migration builder API.

Error: A migration function must return a truthy value or a promise that resolves to a truthy value.

The migration function did not return anything; it needs to return the migration object or a promise.

fix

Add return migration; at the end of your migration function.

Invalid config: contentType is required for transformEntries.

Missing required property 'contentType' in the config object passed to migration.transformEntries.

fix

Ensure the config includes a 'contentType' key set to the ID of the content type to transform.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

contentful-managementrequiredMakes API calls to Contentful's management API under the hood.

Agent activity

10 hits · last 30 days

node

Resources

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

packagecontentful-migration ↗

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