Migrating your application code

Once your content is in Contentstack, the next step is the code that reads from the CMS. The migration tool reads your repository, detects the framework and data-access approach, and rewrites the data layer in place.

What you'll learn

• What the code migration changes and what it preserves

• Which inputs the code step needs from the content step

• How references and rich text differ after migration

• How the migration verifies itself

What it changes and preserves

The code migration is mechanical and minimal. It detects your language, framework, and data-access approach, then migrates in the same shape: REST stays REST, GraphQL stays GraphQL, and Live Preview is reimplemented to match what was there. It preserves your function and component contracts and matches the surrounding code style rather than forcing a rewrite.

Inputs from the content step

The code step needs two files the content step produced:

• mapper.json gives the Contentful-field-UID to Contentstack-field-UID mapping, so rewritten queries reference the correct field names.

• metadata.json supplies the new stack's Delivery SDK credentials: the stack API key, delivery token, environment, and a preview token if Live Preview is enabled.

Set the credentials in the migrated app's local .env file, which should be gitignored. Use the stack_api_key value for the API key, not stack_id.

Reference and rich text differences

Two differences need attention after migration:

• Contentstack resolves references to arrays, not single objects. Every reference dereference becomes safe array access, such as entry.author?.[0]. Audit null safety wherever the old code assumed a single referenced object.

• Contentful rich text becomes Contentstack JSON RTE. Embedded entries and assets are preserved as references and rendered through the appropriate renderer.

How verification works

The code migration runs a suite of post-migration checks covering Contentful residue, field access, SDK initialization, build, secrets, references, rich text, locales, assets, GraphQL, and Live Preview. A clean build is necessary but not sufficient, because a build cannot catch a wrong field UID or a reference-array bug. After the checks pass, smoke-test live queries against the real Contentstack stack before you treat the code as done.

When the migration is uncertain about a field UID or a behavior, it leaves a TODO(migration) comment at the call site rather than guessing silently. Review every one.

Key takeaways

• The code migration preserves your framework, approach, and contracts.

• It needs mapper.json and metadata.json from the content step.

• Use stack_api_key for the API key and keep tokens in a gitignored .env.

• Convert reference access to safe array access and check null safety.

• A green build is not enough; smoke-test live queries and review every TODO.