Migrating from Contentful to Contentstack in depth
What this guide is for
This guide is for developers moving a project from Contentful to Contentstack. It covers both the content migration (content types, entries, assets, locales, and more) and the application code that reads from the CMS.
There are two ways to run the migration, and this guide documents both. The guided path uses an AI skill that runs in an agentic chat window and orchestrates the migration for you. The expert path uses the Contentstack CLI plugin directly, one command at a time. Both paths run the same underlying tooling, so you can switch between them.
How to use this guide
If you want the fastest route, read chapters The guided path: migrate with the AI skill and The expert path: migrate with CLI commands and let the AI skill drive.
If you want full control over each step, read chapters The guided path: migrate with the AI skill and Migrating your application code for the CLI commands and flags.
If you need to migrate application code, read chapter What migrates, what needs manual work, and how to verify.
Before you treat the migration as done, read chapter Troubleshooting and next steps for the validation checklist and the known limitations.
What this tool does and how it works
The migration is built from two pieces that work together: an AI skill and a Contentstack CLI plugin called @contentstack/cli-external-migrate. The skill handles orchestration and explanation. The plugin handles the actual data work.
One principle governs the whole design: the AI guides, the tooling executes. The AI never transforms your content. It reads your environment, decides which steps to run, executes trusted CLI commands, explains each decision, and validates the result. The export, conversion, and import all run through deterministic CLI tooling. This keeps the migration transparent and repeatable, which matters when you point it at a real space.
What you'll learn
How the AI skill and the CLI plugin divide responsibilities
Which platform differences the migration handles for you
What a full run produces on disk
When to choose the guided path over the expert path
The two paths
The guided path runs inside an agentic chat window. You describe what you want to migrate, and the skill checks prerequisites, runs the migration, shows progress, and produces a summary. It executes the same commands you would run by hand, so nothing is hidden.
The expert path runs the CLI commands yourself. You get the same export, conversion, audit, and import steps as discrete commands with flags you control. Use this path when you want to inspect intermediate output, script the migration, or run a subset of steps.
How platform differences are handled
Contentful and Contentstack model some things differently, and the tooling translates between them:
Contentful environments map to Contentstack branches (master maps to main).
Contentful rich text converts to Contentstack JSON Rich Text Editor (RTE) format, with embedded entries and assets preserved as references.
Contentful references resolve to Contentstack reference fields, which return arrays rather than single objects.
Contentful roles map to built-in Contentstack roles where they match, and to custom roles where they do not.
DAM marketplace app fields (Cloudinary, Bynder, Brandfolder, Frontify, Digizuite, Aprimo) map to the correct Contentstack asset shape.
What a run produces
A full content run creates a fresh Contentstack stack in your organization and writes a set of artifacts to your workspace directory: the Contentful export JSON, a Contentstack import bundle, a mapper.json that records the field-UID mapping between source and target, a metadata.json with the new stack's credentials, and import logs. The code migration uses the mapper and metadata files, so keep the workspace directory until the whole migration is done.
Key takeaways
The AI skill orchestrates; the CLI plugin does the data work.
The AI never transforms content directly, which keeps the migration safe and repeatable.
The tooling translates platform differences such as environments, rich text, references, and roles.
A run produces an export, a bundle, a field mapper, stack credentials, and logs.
Frequently asked questions
What are the two ways to run the migration from Contentful to Contentstack?
Use the guided path in an agentic chat window (AI skill orchestration) or the expert path by running @contentstack/cli-external-migrate commands directly.
Does the AI skill transform or modify content during the migration?
No. The AI guides and orchestrates deterministic CLI commands; export, conversion, and import are executed by the CLI tooling for repeatable results.
How are common platform differences handled during migration?
The tooling translates key differences, including environments to branches, rich text to Contentstack JSON RTE, references to reference fields, and role mappings.
What files and artifacts does a full migration run produce?
It creates a new Contentstack stack and writes artifacts such as the Contentful export JSON, a Contentstack import bundle, mapper.json, metadata.json, and import logs.
Why should you keep the workspace directory after the content migration completes?
The code migration relies on mapper.json and metadata.json to map fields and access the new stack, so the workspace is required until the full migration is done.