Registry / cms / contentful-migrate-bse

contentful-migrate-bse

library0.1.0jsnpmunverified

A command-line tool and library for managing Contentful content model migrations using incremental scripted changes (CMS as Code). Current stable version 0.1.0 (Node >=8). Based on the Contentful Migration tool syntax, it tracks migration state per content type in a dedicated 'Migration' content type. Differs from contentful-migration by providing state management, bootstrapping from existing spaces, and per-content-type folder organization.

cms devops

npm install contentful-migrate-bse

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-MIGRATE

contentful-migrate-bse

cmsjavascriptv0.1.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.

default

✓ module.exports.up = migration => { ... }

✗ export function up(migration) { ... }

CommonJS module format with exports.up / exports.down required; ES module syntax not supported.

ctf-migrate (CLI)

✓ npx ctf-migrate init

✗ ctf-migrate init (without npx or global install)

Recommended to use npx to avoid global install; requires CONTENTFUL_MANAGEMENT_ACCESS_TOKEN env var.

migration scripts

✓ module.exports.description = "Create Post"; module.exports.up = migration => { ... }; module.exports.down = migration => { ... };

✗ export const description = "Create Post"; export function up(migration) { ... }

Scripts must export description, up, and down as CommonJS module properties.

Shows initialization and bootstrapping of Contentful space using ctf-migrate CLI.

const { execSync } = require('child_process'); // Set environment variables (or use --access-token etc.) process.env.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN = process.env.CTF_CMA_TOKEN ?? ''; process.env.CONTENTFUL_SPACE_ID = process.env.CTF_SPACE_ID ?? ''; process.env.CONTENTFUL_ENV_ID = process.env.CTF_ENV_ID ?? 'master'; // 1. Initialize the space (creates Migration content type) try { execSync('npx ctf-migrate init', { stdio: 'inherit' }); } catch (e) { console.error('Init failed. Ensure credentials are set.'); process.exit(1); } // 2. Bootstrap existing content types into migration scripts try { execSync('npx ctf-migrate bootstrap --content-types post,banner', { stdio: 'inherit' }); } catch (e) { console.error('Bootstrap failed.'); process.exit(1); } console.log('Migration scripts generated in ./migrations/');

Debug

Known issues

gotchaThe `init` command will fail if the 'Migration' content type already exists.

fix

If already initialized, you may skip init or delete the Migration content type via the Contentful web app before re-running.

affects: >=0.1.0

breaking`bootstrap` deletes existing migration scripts. It consolidates all current content type state into a single script, losing history.

fix

Use with caution; version-control your migrations directory to recover history if needed.

affects: >=0.1.0

deprecatedThe package requires Node >=8, which is end-of-life. Consider upgrading to Node 18+.

fix

Use nvm or similar to switch to a current Node version. Note that contentful-migrate may not be actively maintained for newer Node versions.

affects: >=0.1.0

gotchaEnvironment variables CONTENTFUL_MANAGEMENT_ACCESS_TOKEN, CONTENTFUL_SPACE_ID, and CONTENTFUL_ENV_ID must be set correctly; otherwise CLI commands fail with cryptic errors.

fix

Verify credentials and space/environment IDs. Use --access-token, --space-id, --environment-id options as fallback.

affects: >=0.1.0

breakingMigration scripts must follow a specific folder structure: `migrations/<content-type-id>/timestamp-description.js`. Incorrect structure causes `bootstrap` to fail.

fix

Ensure scripts are placed in the correct subfolder matching the content type ID (e.g., `migrations/post/1513695986378-create-post.js`).

affects: >=0.1.0

Errors

Common errors & fixes

Content type with id "migration" already exists.

`ctf-migrate init` run on a space that already has a 'Migration' content type.

fix

If you want to reinitialize, delete the 'Migration' content type via the Contentful web app or skip init if already present.

Error: Cannot find module 'contentful-migration'

Missing peer dependency `contentful-migration` when using the package programmatically.

fix

Install the peer dependency: `npm install contentful-migration`

Error: EACCES: permission denied, mkdir 'migrations'

Running `ctf-migrate` in a directory without write permissions.

fix

Run the command in a project directory where you have write access, or use `sudo` (not recommended) on Unix systems.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

contentful-migrationrequiredcore dependency for executing migration scripts

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bemaxima/contentful-migrate ↗

packagecontentful-migrate-bse ↗

homepagehttps://github.com/bemaxima/contentful-migrate#readme ↗