Registry / devops / contentful-schema-diff

contentful-schema-diff

library0.10.3jsnpmunverified

A CLI tool to automatically generate a starting point for Contentful schema migrations between two spaces or environments. It compares content type definitions from export files or directly from Contentful spaces via the Management API, producing TypeScript or JavaScript migration files compatible with the contentful-migration tool. Version 0.10.3 is the latest stable release. Originally built by Watermark Church to simplify Contentful schema changes. Key differentiator: automates migration scaffolding by diffing actual Contentful schemas, reducing manual effort. Outputs TypeScript by default, which requires additional steps to run (see warnings). Release cadence is low, with infrequent updates.

devops

npm install contentful-schema-diff

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTFUL-SCHEMA-

contentful-schema-diff

devopsjavascriptv0.10.3

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.

CLI usage

✓ contentful-schema-diff --from <from> --to <to> --token <token>

✗ contentful-schema-diff --from <space> --to <space> (without --token when downloading directly, causing error)

The tool is a CLI binary, not a library. It does not export any API for programmatic use.

Installs the CLI globally and generates a migration from production to dev using a management token.

npm install -g contentful-schema-diff contentful-schema-diff --from prod-space --to dev-space --token $CONTENTFUL_MANAGEMENT_TOKEN

Debug

Known issues

gotchaOutput files are TypeScript by default, but contentful-migration expects JavaScript. You need to compile or rename files, or use the --js flag.

fix

Use --js flag to output JavaScript directly, or compile TypeScript files before running with contentful-migration.

affects: >=0.0.0

gotchaThe --from and --to arguments refer to the old and new schema respectively. 'from' is the old (production), 'to' is the new (dev). Getting these reversed will generate a migration that rolls back changes.

fix

Double-check that --from is the original space/environment and --to is the target space/environment.

affects: >=0.0.0

deprecatedThe --token option is marked as optional but is required when using space IDs directly (not export files).

fix

Always provide a Contentful management token if you are comparing spaces or environments without pre-exported JSON files.

affects: >=0.0.0

Errors

Common errors & fixes

error: unknown option '--someflag'

Using an option not recognized by the CLI (e.g., --to-env instead of --to).

fix

Check available options with --help. Correct flag names: --from, --to, --token, --content-type, --out, --js, --ts, --one-file, --no-format, --help.

Error: Cannot find module 'contentful-management'

Missing or broken installation of the required dependency contentful-management.

fix

Reinstall the package globally: npm install -g contentful-schema-diff

TypeScript files cannot be run with contentful-migration

Tool outputs .ts files by default, but contentful-migration requires .js.

fix

Use the --js flag to output JavaScript files, or compile the TypeScript files with tsc before running the migration.

Upgrade

Version history

0.10.3latest on npm

Audit

Dependencies

contentful-managementoptionalUsed to fetch content types from Contentful spaces/environments when using the --token option

yargsrequiredCLI argument parsing

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/watermarkchurch/contentful-schema-diff ↗

packagecontentful-schema-diff ↗

homepagehttps://github.com/watermarkchurch/contentful-schema-diff ↗