Contentstack Migration Companion

contentstack-migration-companion

Guide a user through migrating a project from Contentful to Contentstack — first the content (content types, entries, assets, locales) via the Contentstack CLI migrate plugin, then the website code that reads from the CMS.

This is a sequential workflow where each step produces output that the next step consumes (the create command produces a populated stack and a bundle with credentials, which feeds the code migration). Treat the artifact paths and counts that each command prints as state you must capture and carry forward.

Operating principles

Follow these throughout — they matter more than any single command:

• Work in a unique session workspace. At the very start of Step 1, create a

session-scoped directory by running:

  SESSION_ID=$(date +%Y%m%d-%H%M%S) && SESSION_DIR="/tmp/migrate-to-cs/$SESSION_ID" && mkdir -p "$SESSION_DIR" && echo "SESSION_DIR=$SESSION_DIR"

Record the printed SESSION_DIR value (e.g. /tmp/migrate-to-cs/20260608-143022) and carry it as a concrete literal through every shell command in this migration — do not regenerate it. This keeps each migration run isolated so concurrent sessions and re-runs never collide. If the user points you to a different workspace, use their path instead.

• Bundled scripts & references live next to this skill — resolve them via `{SKILL_DIR}`.

This skill ships helper scripts (a scripts/ folder) and reference docs (a references/ folder) alongside this `SKILL.md` file. Wherever these instructions write {SKILL_DIR}, substitute the absolute path of the directory this SKILL.md was loaded from — i.e. the skill's own install directory. Do not assume a fixed path. The location differs by AI assistant, by OS, and by whether the skill was installed per-project or per-user — for example it may be <project>/.claude/skills/contentstack-migration-companion, ~/.claude/skills/contentstack-migration-companion, or a Windows path like %USERPROFILE%\.claude\skills\contentstack-migration-companion. Determine the real path once (it is the folder you read this SKILL.md from; if unsure, search the workspace and home directory for */contentstack-migration-companion/SKILL.md), and for shell commands set it as a variable up front (SKILL_DIR="<that absolute path>") so bundled scripts can be invoked as "$SKILL_DIR/scripts/<name>". The bundled scripts self-locate their own siblings, so once you invoke them by absolute path they work regardless of your current directory.

• Pin the Node version for the whole session. A machine often has several Node versions

(system, Homebrew, multiple nvm installs) and a non-interactive shell may resolve an old one (e.g. /usr/local/bin/node v14) ahead of the user's nvm default. The Step 1 prereq checker finds the highest installed Node ≥ 20 and reports its directory as node.bin_dir in the JSON. Record that value as a concrete literal NODE_BIN_DIR and prefix every `csdx`, `npm`, and `contentful` command for the rest of the migration with it, e.g. PATH="<NODE_BIN_DIR>:$PATH" csdx migrate:create …. This guarantees the CLI runs on the Node the prereq check validated, not whatever an unconfigured shell picks first. If node.bin_dir is absent (older check output), fall back to the plain command.

• One step at a time, and show the result. After each command, surface the meaningful

output to the user — the summary tables, the counts, the artifact path — not a wall of raw logs. The user is watching this like a progress bar; give them a clean status, then the path/handle the next step needs.

• Track migration progress with the checklist. At each [PROGRESS] trigger below, output

a progress block in your response using these emoji: ✅ = completed, ⏳ = currently running, ⬜ = not yet started. Example for Step 3 in progress:

  **Migration progress**
  - ✅ Step 1 — Prerequisites & inputs
  - ✅ Step 2 — Install migrate plugin
  - ⏳ Step 3 — Content Migration
  - ⬜ Step 4 — Code Migration

Output it at two moments: (1) at the start of each step, and (2) when each step's eval passes. Only one step is ⏳ at a time. Step 4 stays ⏳ through all sub-steps 4.1–4.6. Step 5 (Welcome) is not tracked — it triggers automatically once Step 4 is ✅.

• Gate the destructive or expensive steps. Confirm before logging in, before creating a

new stack, and before editing the user's code. These either touch live accounts or modify their repo, so a quick "ready to proceed?" prevents nasty surprises.

• Capture the outputs explicitly. When a command prints a bundle path, a log directory,

or a stack API key, record the exact path/value and reuse it verbatim. Do not guess paths — read them back from the command output.

• Browser-based login is normal here. csdx auth:login --oauth opens the user's browser;

the terminal then blocks and auto-detects when they finish. Run it, tell the user to complete login in the browser, and simply wait for the command to return — do not try to script the browser or kill the command.

• Currently Contentful is the only supported source. Do not ask the user which legacy

platform they're on; assume Contentful. (The CLI flag is --source contentful.)

• If a step fails, stop and diagnose rather than barrelling ahead. Most failures here are

recoverable (expired token → re-login, missing content model → inform the user), and the relevant recovery is described in the step that can fail.

• Never display code in your text output. Do not show shell commands, code snippets,

scripts, or any fenced code blocks (``` blocks) in your chat messages at any point during the migration. Just run commands silently and report the result in plain prose. The user sees tool calls in the tool panel — repeating code in chat is noise.

The migration at a glance

Work through them in order. The sections below give the exact commands, what to show the user, and what to carry forward.

Self-contained skill. Everything Step 4 needs — the full code-migration procedure, the

Contentful → Contentstack SDK reference (references/), and the eval scripts (scripts/) —

ships inside this one skill. There is no separate code-migration skill to install; resolve the

bundled files via {SKILL_DIR} as described above.

---

Step 1 — Prerequisites & inputs

[PROGRESS] Output the migration progress block:

Step 1 → "in_progress", Steps 2–4 → "pending".

1.0 — Create session workspace

Before doing anything else, create the unique session directory for this migration run:

SESSION_ID=$(date +%Y%m%d-%H%M%S) && SESSION_DIR="/tmp/migrate-to-cs/$SESSION_ID" && mkdir -p "$SESSION_DIR" && echo "SESSION_DIR=$SESSION_DIR"

Record the printed `SESSION_DIR` path exactly (e.g. /tmp/migrate-to-cs/20260608-143022). Substitute this concrete value wherever these instructions reference $SESSION_DIR. Do not regenerate it — every step in this migration must use the same directory so artifacts chain correctly.

Tell the user: "Session workspace created at <SESSION_DIR>."

1.1 — Detect the Python 3 command

Run this to find the correct Python 3 command for this environment:

if python3 --version 2>&1 | grep -q "Python 3"; then
  PYTHON_CMD=python3
elif python --version 2>&1 | grep -q "Python 3"; then
  PYTHON_CMD=python
else
  PYTHON_CMD=""
fi
echo "PYTHON_CMD=$PYTHON_CMD"

Record `PYTHON_CMD` exactly as printed. Substitute $PYTHON_CMD wherever these instructions show a Python invocation — do not hardcode python3 or python.

If PYTHON_CMD is empty, stop immediately and tell the user:

"Python 3 is required but not found. Install it from python.org or via your package manager

(e.g. brew install python3 on macOS, sudo apt install python3 on Ubuntu,

or download the installer from python.org on Windows), then try again."

Do not proceed past this point until Python 3 is detected.

1.2 — Run the prerequisite checker

Run this single script. It silently evaluates Node.js, installs any missing CLIs (csdx, contentful), checks the Contentstack region and login, and checks the Contentful login and spaces — all in one pass. It outputs a JSON summary:

$PYTHON_CMD "{SKILL_DIR}/scripts/check_prereqs.py"

Parse the JSON result and carry every field forward as session state.

Record the Node bin directory. Capture node.bin_dir from the JSON as the concrete literal NODE_BIN_DIR. Per the "Pin the Node version" principle in the overview, prefix every later csdx, npm, and contentful command with PATH="<NODE_BIN_DIR>:$PATH" so the whole migration runs on the Node the checker validated — not whatever an unconfigured non-interactive shell would resolve first (the checker already picks the highest installed Node ≥ 20, scanning PATH and all nvm installs). If node.bin_dir is missing, fall back to the plain command.

Hard blocker: If the script exits with code 1, Node.js is missing or too old. The reported node.version/node.path reflect the best Node found anywhere on the machine, so the message is accurate even when a newer Node exists but isn't on the default PATH. Stop immediately and tell the user the exact problem:

• node.error == "not_installed" → "Node.js is not installed. Install it via nvm install 22

or from nodejs.org, then try again."

• node.ok == false (e.g. node.version == "v18.x") → "The newest Node I can find is

<version>, but Node 20+ is required. Install a newer one with nvm install 22 && nvm use 22 (or upgrade your system Node), then try again."

Do not continue past this point until Node 20+ is confirmed.

1.3 — Handle missing Contentstack login (if needed)

Skip this sub-step if cs_login.ok is true in the JSON.

If cs_login.ok is false (needs_login) or cs_login.org_uid is null (needs_oauth_reauth), trigger a fresh OAuth login:

csdx auth:login --oauth

Tell the user: _"A browser window is opening — complete the Contentstack login there, then come back here."_ Wait for the command to return (it blocks until the browser flow finishes), then re-run the prereq checker (same command as 1.2) to capture the updated email and org UID.

If the org UID is still missing after the retry, tell the user:

"OAuth login did not store an org UID. Please re-run csdx auth:login --oauth manually, then

let me know when done so I can retry."

1.4 — Handle missing Contentful login (if needed)

Skip this sub-step if contentful_login.ok is true in the JSON.

contentful login is interactive (it needs the user to press Y and paste a token) — you cannot run it as a Bash command. Instruct the user to run it themselves:

"Please run this command in your terminal:

>

```

contentful login

```

>

It will ask 'Continue login on the browser? (Y/n)' — press Y.

A browser window will open — sign in there.

When the browser login completes, the terminal will show 'Paste your token here:' —

copy your Management Token from the browser page and paste it, then press Enter.

Come back here once the login confirms success."

Wait for the user to confirm they have completed the login, then re-run the prereq checker to pick up the new session.

The Management Token is a secret: do not ask the user to share it with you, do not echo it

back in your summaries, and do not write it into any file in this workspace.

1.5 — Show the prerequisites summary and confirm

Once cs_login.ok and contentful_login.ok are both true, display a summary table from the JSON result. Use ✅ for items that look good and ⚠️ for anything that may need attention:

Then ask this single question:

"Everything looks good — ready to proceed? Or would you like to change anything before

we start?

>

- proceed — start the migration

- region — switch the Contentstack region

- contentstack login — switch the Contentstack account

- contentful login — switch the Contentful account"

Wait for the user's answer before continuing.

Region picker — when the user asks to change the region, show this menu and wait for their choice before running the command:

"Which region is your destination stack in?

>

1. AWS-NA — AWS North America

2. AWS-EU — AWS Europe

3. AWS-AU — AWS Australia

4. AZURE-NA — Azure North America

5. AZURE-EU — Azure Europe

6. GCP-NA — Google Cloud North America

7. GCP-EU — Google Cloud Europe"

Map the number to its region code and run:

csdx config:set:region <REGION>   # e.g. csdx config:set:region AWS-EU

Repeat the summary + question until the user confirms they are ready to proceed.

1.6 — Contentful Space ID (select from list)

The contentful_spaces array in the prereq JSON already holds all accessible spaces (populated from the contentful space list call run inside the checker).

If there is exactly one space in the list, select it automatically — do not ask the user. Announce the selection:

"Found one Contentful space: My Marketing Site (abc123). Using it automatically."

Capture its ID as SPACE_ID and continue.

If there are two or more spaces, present them as a numbered menu — do not ask the user to type or paste a Space ID:

1. My Marketing Site  (abc123)
2. Developer Sandbox  (def456)
…

Ask:

"Which space do you want to migrate? Enter the number."

Wait for the answer. Map the number back to the Space ID and capture it as SPACE_ID.

If the list is empty (no spaces parsed), fall back to asking:

"I couldn't list your Contentful spaces. Please enter the Space ID directly."

Then confirm the token can reach the selected space:

contentful space use --space-id <SPACE_ID>

If this fails, the token likely lacks access to that space — tell the user and ask them to re-check the selection or switch to a Contentful account that has the right access.

Eval — Verify Step 1 before proceeding

# Use the Node the checker validated (NODE_BIN_DIR from the prereq JSON).
export PATH="<NODE_BIN_DIR>:$PATH"
$PYTHON_CMD --version   # must print Python 3.x
node --version          # must print v20.x or higher
csdx --version          # must print a version number
csdx auth:whoami        # must print a logged-in email
contentful --version    # must print a version number
contentful space list   # must return a list of spaces — not "You have to be logged in"

(export only affects this one Eval block — shell state does not persist across commands, so later steps must still prefix PATH="<NODE_BIN_DIR>:$PATH" per the overview principle.)

Pass criteria:

• $PYTHON_CMD detected and exits 0 with Python 3.x
• Node major version ≥ 20
• csdx auth:whoami returns an email (not "No user logged in")
• cs_login.org_uid is non-null (captured from prereq JSON in step 1.2 / 1.3)
• contentful space list returns rows without an auth error
• SPACE_ID captured from the user's selection in 1.6

Note: contentful whoami is not available in all CLI versions — use contentful space list

to verify authentication instead.

If every check passes:

[PROGRESS] Output the migration progress block:

Step 1 → "completed", Step 2 → "in_progress", Steps 3–4 → "pending".

Then proceed to Step 2. If any check fails, fix the issue (re-run the relevant sub-step) and re-verify.

---

Step 2 — Install the migrate CLI plugin

[PROGRESS] Output the migration progress block:

Step 1 → "completed", Step 2 → "in_progress", Steps 3–4 → "pending".

The csdx migrate:* commands come from @contentstack/cli-external-migrate. Run this block to install or update it automatically — it is intentionally silent unless something changes or fails:

PLUGIN_NAME="@contentstack/cli-external-migrate"

# Version currently installed (empty string if not installed)
INSTALLED=$(csdx plugins 2>/dev/null \
  | grep -F "$PLUGIN_NAME" \
  | grep -oE '[0-9]+\.[0-9]+\.[0-9]+[^ ]*' \
  | head -1)

# Latest version on npm
LATEST=$(npm view "$PLUGIN_NAME" version 2>/dev/null)

if [ -z "$LATEST" ]; then
  echo "PLUGIN_NPM_UNAVAILABLE"
elif [ -z "$INSTALLED" ]; then
  csdx plugins:install "$PLUGIN_NAME" && echo "PLUGIN_INSTALLED:$LATEST" || echo "PLUGIN_INSTALL_FAILED"
elif [ "$INSTALLED" = "$LATEST" ]; then
  echo "PLUGIN_UP_TO_DATE:$INSTALLED"
else
  csdx plugins:uninstall "$PLUGIN_NAME" \
    && csdx plugins:install "$PLUGIN_NAME" \
    && echo "PLUGIN_UPDATED:$INSTALLED→$LATEST" \
    || echo "PLUGIN_UPDATE_FAILED:$INSTALLED→$LATEST"
fi

Interpret the last line:

• `PLUGIN_UP_TO_DATE:<version>` → already on the latest version; proceed to the Eval. (Stay

silent — don't report "already up to date" to the user.)

• `PLUGIN_INSTALLED:<version>` → freshly installed. Briefly tell the user, then proceed.
• `PLUGIN_UPDATED:<old>→<new>` → uninstalled old version and installed latest. Briefly tell

the user the plugin was updated, then proceed.

• `PLUGIN_INSTALL_FAILED` / `PLUGIN_UPDATE_FAILED:<old>→<new>` → the install or

reinstall errored. Show the user the error output, then display this message and wait:

The automatic plugin install failed. Please run the following command manually in your

terminal, then click Continue when done:

>

```

csdx plugins:install @contentstack/cli-external-migrate

```

After the user clicks Continue, skip straight to the Eval below to verify the plugin is working before proceeding.

• `PLUGIN_NPM_UNAVAILABLE` → npm view returned nothing (network issue or package not yet

published). Show the user this message and wait:

Could not reach npm to check the plugin version. Please run the following command manually

in your terminal, then click Continue when done:

>

```

csdx plugins:install @contentstack/cli-external-migrate

```

After the user clicks Continue, proceed to the Eval below.

Eval — Verify Step 2 before proceeding

csdx migrate --help

Pass criteria:

• Output includes migrate:create (the one-shot command used in Step 3)

If migrate:create is present, update the migration checklist to set cf-step2="completed" and cf-step3="in_progress", then proceed to Step 3. If the command errors or migrate:create is missing, re-run the install block above and re-verify.

---

Step 3 — Content Migration

[PROGRESS] Output the migration progress block:

Steps 1–2 → "completed", Step 3 → "in_progress", Step 4 → "pending".

This single command exports the Contentful space, converts the content to a Contentstack bundle, and imports it into a brand-new stack — all in one shot. The master locale is auto-detected from the export's default locale.

3.0 — Retrieve the stored Management Token

The Contentful CLI stores the token from the login in ~/.contentfulrc.json. Read it now so migrate:create can use it without prompting:

$PYTHON_CMD -c "
import json, sys, pathlib
for p in ['~/.contentfulrc.json', '~/.config/contentful/config.json']:
    f = pathlib.Path(p).expanduser()
    if f.exists():
        d = json.loads(f.read_text())
        tok = d.get('managementToken') or d.get('cmaToken') or d.get('management_token')
        if tok:
            print(tok)
            sys.exit(0)
print('NOT_FOUND', file=sys.stderr)
sys.exit(1)
"

Capture the printed value as CONTENTFUL_MANAGEMENT_TOKEN. Do not display it to the user or write it to any file.

If the token is NOT found (exits 1), tell the user the token could not be resolved. Ask them to run contentful login again, then retry.

3.1 — Confirm before running

Tell the user:

"Ready to start the content migration. This will export your Contentful space, convert

the content, and import it into a new stack under your org. Shall I proceed?"

Wait for confirmation before running the command.

3.2 — Run migrate:create (output captured to log file)

Run from $SESSION_DIR so that the import logs/ directory and _backup_*/ are written there, keeping the user's project directory clean. Pipe through tee so output streams live and is also saved for parsing:

cd "$SESSION_DIR" && \
csdx migrate:create --source contentful \
  --space-id "$SPACE_ID" \
  --source-token "$CONTENTFUL_MANAGEMENT_TOKEN" \
  --org "$ORG_UID" \
  --download-assets \
  --output "$SESSION_DIR" \
  --workspace "$SESSION_DIR" \
  -y \
  2>&1 | tee "$SESSION_DIR/migrate-create.log"

Flag notes:

• --space-id / --source-token — Contentful source (token resolved in 3.0)
• --org — the org UID captured in Step 1; a new stack is created here
• --source contentful — declares Contentful as the migration source
• --download-assets — include asset binaries in the migration
• --output "$SESSION_DIR" — bundle written to $SESSION_DIR/bundle/
• --workspace "$SESSION_DIR" — export JSON saved to $SESSION_DIR/export.json
• -y — skip internal confirmation prompts (we already confirmed above)
• cd "$SESSION_DIR" — ensures logs/ and _backup_*/ land in the session dir, not CWD

The command runs three phases and prints this progression:

Phase 1 — Export (streams fetch progress, ends with the entity-count table):

┌────────────────────────┐
│ Exported entities      │
├───────────────────┬────┤
│ Content Types     │ 16 │
│ Entries           │ 53 │
│ Assets            │ 21 │
│ Locales           │ 2  │
│ …                 │ …  │
└───────────────────┴────┘
Stored space data to json file at: <SESSION_DIR>/export.json

Phase 2 — Convert (transforms export into Contentstack bundle):

  validate   ✓  export.json
  extract    ✓  2 locales · 16 types
  transform  ✓  53 entries · 13 types  →  <SESSION_DIR>/bundle
  Bundle: <SESSION_DIR>/bundle (16 types, 53 entries)

Phase 3 — Import (creates stack, imports content, ends with the summary box):

✓ Stack created · via cma
──────────────────────────────────────
  Stack name : Contentful Migration 2026-06-08
  Stack key  : blt3e69b8da307655a7
  Region     : AWS-NA
──────────────────────────────────────
… (import progress) …
SUCCESS: Successfully imported the content to the stack named … with the API key blt… .
SUCCESS: The log has been stored at: <SESSION_DIR>/logs
✓ Bundle metadata written: <SESSION_DIR>/bundle/metadata.json
✓ Migration complete
──────────────────────────────────────
  Stack name : Contentful Migration 2026-06-08
  Stack key  : blt3e69b8da307655a7
  Region     : AWS-NA
──────────────────────────────────────

3.3 — Parse the output and extract session variables

Once the command returns, parse the captured log with exact patterns matching the real output:

$PYTHON_CMD - <<'PYEOF'
import re, pathlib, os

raw = pathlib.Path(os.environ["SESSION_DIR"] + "/migrate-create.log").read_text()
# Strip ANSI escape codes — the import phase wraps paths in color sequences
log = re.sub(r'\x1b\[[0-9;]*m', '', raw)

# Patterns matched against real command output
export_json = re.search(r'Stored space data to json file at:\s+(\S+)',  log)
bundle_dir  = re.search(r'Bundle:\s+(\S+)',                             log)
stack_name  = re.findall(r'Stack name\s*:\s*(.+)',                      log)
stack_key   = re.findall(r'Stack key\s*:\s*(blt\w+)',                   log)
region      = re.findall(r'Region\s*:\s*(\S+)',                         log)
log_dir     = re.search(r'SUCCESS: The log has been stored at:\s+(\S+)',log)
metadata    = re.search(r'Bundle metadata written:\s+(\S+)',            log)

session_dir = os.environ["SESSION_DIR"]
# Use last match for stack fields — the final summary box is authoritative
print("EXPORT_JSON="   + (export_json.group(1).strip() if export_json else session_dir + "/export.json"))
print("BUNDLE_DIR="    + (bundle_dir.group(1).strip()  if bundle_dir  else session_dir + "/bundle"))
print("STACK_NAME="    + (stack_name[-1].strip()       if stack_name  else "UNKNOWN"))
print("STACK_KEY="     + (stack_key[-1].strip()        if stack_key   else "UNKNOWN"))
print("REGION="        + (region[-1].strip()           if region      else "UNKNOWN"))
print("LOG_DIR="       + (log_dir.group(1).strip()     if log_dir     else "UNKNOWN"))
print("METADATA_PATH=" + (metadata.group(1).strip()    if metadata    else session_dir + "/bundle/metadata.json"))
PYEOF

Capture each printed KEY=value as a session variable:

Also set the mapper path (always $BUNDLE_DIR/mapper.json):

MAPPER_PATH="$BUNDLE_DIR/mapper.json"

If any value is UNKNOWN, check $SESSION_DIR/migrate-create.log directly for the line and set it manually before continuing.

3.4 — Show the user a progress summary

Show the entity-count table and the final stack summary, both taken from the captured log:

# Entity count table from Phase 1 (export)
grep -A 18 'Exported entities' "$SESSION_DIR/migrate-create.log" | head -20

# Final stack summary box from Phase 3 (last occurrence)
grep -A 4 'Stack name' "$SESSION_DIR/migrate-create.log" | tail -6

Report in plain prose:

"Content migration complete — stack `$STACK_NAME` ($STACK_KEY, $REGION) is ready."

Handle token expiry mid-run

The Contentstack OAuth token can expire during a long import. The symptom in the log is:

stack creation failed.
  CMA:  401 The provided access token is invalid or expired or revoked

Re-authenticate and re-run from step 3.1:

csdx auth:login --oauth

The command is safe to re-run — it creates a fresh stack each time.

Eval — Verify Step 3 before proceeding

Confirm the key artifacts exist:

ls -lh "$METADATA_PATH"
ls -lh "$MAPPER_PATH"

Run the bundled import summary parser to verify entity counts match what was exported:

$PYTHON_CMD "$SKILL_DIR/scripts/parse_import_summary.py" "$LOG_DIR" --export "$EXPORT_JSON"

Pass criteria:

• STACK_KEY starts with blt (a real stack was created)
• METADATA_PATH and MAPPER_PATH both exist
• SUCCESS: Successfully imported… line is present in the captured log
• Imported counts match exported counts; any divergence must be explained before proceeding

Present the counts table to the user:

Module          Imported   (Exported)
Locales         2          2
Content Types   16         16
Assets          21         21
Entries         53         53
✓ Imported into stack "<STACK_NAME>" (<STACK_KEY>)

If all pass, update the migration checklist to set cf-step3="completed" and cf-step4="in_progress", then proceed to Step 4. If counts diverge or artifacts are missing, surface the discrepancy and point the user at $LOG_DIR — do not proceed until resolved.

Session variables carried into Step 4

---

Step 4 — Code Migration

[PROGRESS] Output the migration progress block:

Steps 1–3 → "completed", Step 4 → "in_progress".

With the content now in Contentstack, migrate the application code that reads from the CMS. This step runs a full detect → plan → rewrite → eval cycle with 13 post-migration checks.

4.1 — Collect inputs

`repoPath` — local file system path to the application to migrate. Ask the user:

"What is the local path to the codebase you want to migrate? (e.g. /Users/you/projects/my-app)"

If it's a remote git repo, clone it first:

>

```bash

cd "$SESSION_DIR" && git clone <REPO_URL>

```

>

Then use the cloned directory as repoPath.

`mapperPath` — the field-mapping JSON produced by Step 3. Confirm it exists:

ls -lh "$SESSION_DIR/bundle/mapper.json"

If the file is at a different path (e.g. the user used a custom workspace), ask them to confirm the exact path.

Read mapperPath with the Read tool and extract the fieldMapping arrays from each content type to build the Contentful-field-UID → Contentstack-field-UID table. Present the extracted table to the user for confirmation before proceeding.

`metadataPath` — the credentials JSON written by Step 3's import. Confirm it exists and read it:

ls -lh "$SESSION_DIR/bundle/metadata.json"

Read metadataPath with the Read tool. It supplies the new stack's Delivery SDK credentials so you do not have to ask the user for them:

The region (e.g. AWS-NA) comes from csdx config:get:region. Treat the tokens as secrets — never echo them back or write them into files in this workspace; only set them in the migrated app's local .env (which should be gitignored). If metadata.json is missing, fall back to asking the user for CS_API_KEY, CS_DELIVERY_TOKEN, and CS_ENVIRONMENT.

4.2 — Logging

First resolve {SKILL_DIR} (see the "Bundled scripts & references" operating principle) — the directory this skill is installed in — and set it as a shell variable so every command below can reach the bundled scripts portably, on any OS or assistant:

SKILL_DIR="<absolute path to this skill's install dir>"   # the folder holding this SKILL.md

From the first action in this step, record everything to the session log using "$SKILL_DIR/scripts/log.sh":

• log.sh <target> user-input "<what the user asked/answered>" — every user input/communication.
• log.sh <target> decision "<detection results, choices, assumptions, guessed UIDs>".
• log.sh <target> ai-action "<files/queries you changed>" and communication "<what you told the user>".
• log.sh <target> exception "<any error, blocker, or uncertainty you hit>" — log all exceptions.
• Run shell commands through it so output + exit codes are captured and failures auto-log as

exceptions: log.sh <target> run "typecheck" -- npx tsc --noEmit.

End with log.sh <target> summary. The log lands in <target>/.migration/ (session.log + session.jsonl + per-command output). See "$SKILL_DIR/scripts/README.md".

4.3 — Reference (read first)

The complete, source-verified mapping for every API, response shape, query operator, rich-text renderer, asset transform, GraphQL query, and Live Preview API lives in:

`{SKILL_DIR}/references/CONTENTFUL_TO_CONTENTSTACK_MIGRATION_CONTEXT.md` (read it with the Read tool from this skill's install dir — see the {SKILL_DIR} operating principle)

Read it in full before doing anything. It is the single source of truth — follow it; do not rely on prior knowledge where the doc is specific. Key map:

• §0.1 — detect the data-access approach (decision table)
• §1–§16 — REST Delivery SDK (@contentstack/delivery-sdk) mapping
• §17 — GraphQL Content API migration
• §18 — Live Preview / draft mode migration
• §19 — raw REST / fetch and framework source plugins
• §13 gotchas, §15 checklist

4.4 — Procedure

1. DETECT (doc §0.1). Determine the app's language, framework, and which data-access approach(es) it uses, plus whether it implements Live Preview / draft mode. Migrate in the SAME language and framework, preserving the SAME approach (REST→REST, GraphQL→GraphQL, preview→preview). Report findings and PAUSE for confirmation.

2. PREREQUISITES. Confirm the target Contentstack stack already has the matching content model and published content, and confirm the Contentful-field-ID → Contentstack-field-UID map from step 4.1. If any UIDs are unknown, infer from a sample Contentstack entry and FLAG every guess. Confirm env vars (CS_API_KEY, CS_DELIVERY_TOKEN, CS_ENVIRONMENT, + region/branch, + preview token if Live Preview) — these come from metadataPath (step 4.1), not the user (use stack_api_key, NOT stack_id, for CS_API_KEY). If the content model or entries do not yet exist in Contentstack, STOP — code migration requires content to be imported first (Steps 1–3).

3. PLAN. Produce a table: file:line → source call → Contentstack equivalent (cite the doc section) → field-UID dependencies → risk notes. Show it and PAUSE before editing any file.

4. MIGRATE per the doc, following the section matching each detected approach:

• REST Delivery SDK: §1–§16. GraphQL: §17. Raw REST / framework plugins: §19.
• Rich text / assets / locales / pagination: §9–§12.

Make minimal, mechanical edits that match surrounding code style and the framework's existing data-fetching idioms. Preserve function/component contracts.

5. LIVE PREVIEW. If step 1 found preview/draft-mode, reimplement it per §18, matching the source's scope (routes, components, SSR vs client, click-to-edit vs read-only). Keep preview tokens server-side and preserve existing preview gating/routing.

6. VERIFY — run the eval suite (this is mandatory, not optional). Install deps first so the build eval is meaningful, then run the bundled evals in parallel:

   bash "$SKILL_DIR/scripts/run-all.sh" <path-to-migrated-app>

For maximum parallelism you may instead spawn one agent per "$SKILL_DIR/scripts/"NN\_\*.sh. See "$SKILL_DIR/scripts/README.md" for what each check catches and exit-code semantics.

• **Hard-gate FAIL/ERROR (residue, field-access, sdk-init, build, secrets) ⇒ the migration is NOT

done.** Fix and re-run until they pass.

• Triage every review-eval finding at its file:line — static greps flag _suspects_, not

proven bugs. Fix the true positives; state explicitly why any remaining ones are safe. Never dismiss findings silently.

• A green build is necessary but not sufficient — it cannot catch reference-array bugs, wrong

field UIDs, or RTE output. Still smoke-test live queries against the real Contentstack stack.

• For anything the doc marks "verify against current docs" (GraphQL hosts/headers, Live Preview

front-end API), confirm before finalizing rather than guessing.

4.5 — Guardrails

• Do NOT modify content modeling or move/import entries — out of scope for this step.
• Convert every reference dereference to safe array access (?.[0]) and audit null safety

(Contentstack resolves references to arrays, not single objects).

• When a UID or behavior is uncertain, leave a // TODO(migration): comment and list it — never

guess silently.

4.6 — Wrap up

[PROGRESS] Output the migration progress block:

Steps 1–4 all → "completed". Then immediately proceed to Step 5.

Give the user a final summary of the whole migration journey:

• Content: counts imported into the stack (from Step 3).
• Code: files changed, the rich-text rendering strategy chosen, guessed UIDs to verify, and

any TODO(migration) call sites still needing attention.

• Eval results: whether all hard gates passed and which review findings remain to triage.
• Detection summary: language/framework/approach(es) detected; whether Live Preview was

present and how it was reimplemented; every guessed UID; every TODO; and any call site not fully migrated (geo queries, locale: '*', cross-space ResourceLinks, GraphQL features without an equivalent).

• Next steps: set the CS_* env vars in the app's local .env from metadata.json

(CS_API_KEY = stack_api_key, CS_DELIVERY_TOKEN = delivery_token, CS_ENVIRONMENT = environment, plus CS_PREVIEW_TOKEN = preview_token if Live Preview, and the region from csdx config:get:region), run the app against Contentstack, and verify pages render.

---

Step 5 — Welcome to Contentstack 🎉

The migration is complete. Display the following message to the user — render it exactly as shown, preserving the section headings, icons, and line breaks:

---

╔══════════════════════════════════════════════════════════════════╗
║                                                                  ║
║   🚀  Welcome to Contentstack!                                   ║
║                                                                  ║
║   The Agentic Experience Platform                                ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

"The world's best digital experiences run on Contentstack."

🎊 Your migration is complete.

Your content, content types, assets, and website code have all successfully moved from Contentful to Contentstack. Here's a quick recap of what just happened:

📂 Where to find your migrated files

Using the exact paths captured during this session, fill in and display this table:

Do not use default or guessed paths — substitute only the real paths you captured from each step's command output.

---

🌟 You're now on the platform trusted by the world's top brands

Contentstack powers digital experiences for enterprises across retail, media, finance, and beyond — delivering content at scale, across every channel, without compromise.

Here's what you've unlocked:

---

🚦 Recommended next steps

1. Verify your live site — start your app with the new CS_* env vars and confirm pages render against Contentstack. 2. Explore the Contentstack dashboard — invite your team, set up roles, and configure publishing workflows. 3. Set up webhooks & automation — trigger deploys, Slack alerts, or custom workflows on publish events. 4. Review the Contentstack Docs — contentstack.com/docs is your go-to for Delivery SDK, GraphQL, and Live Preview guides. 5. Talk to your account team — let them know you're live; they can unlock additional features and walk you through advanced capabilities.

---

💡 Tip: Bookmark the Contentstack Developer Hub — it has SDK references, starter apps, and video tutorials to help you get the most out of your new platform.

---

Congratulations on completing your migration. You've made the right call — the world's best digital experiences are built on Contentstack, and now yours will be too. 🚀

Contentful → Contentstack Migration Context (for AI Agents)

Purpose of this file. This is a reference context document for AI coding models tasked

with migrating a web application that consumes Contentful so that it consumes

Contentstack instead. It maps concepts, SDK APIs, query operators, field types,

rich-text rendering, assets, locales and pagination from the Contentful JS SDKs to the

Contentstack TypeScript Delivery SDK (@contentstack/delivery-sdk) and its helper

library (@contentstack/utils).

>

It covers all the common ways a web app consumes Contentful, not just one SDK:

the REST Delivery SDK (contentful), the GraphQL Content API (§17), **Live Preview /

draft mode** (§18), raw REST / fetch access and framework source plugins (§19). Always

begin by detecting which approach(es) the target app uses (§0.1) and migrate like-for-like

— REST→REST, GraphQL→GraphQL, preview→preview — preserving the app's language and framework.

>

Scope: _application / SDK code migration_ — i.e. rewriting the data-fetching and

rendering layer of a website. It is not a content/data ETL guide (moving entries

between stacks is a separate task done via the Contentstack Management API / CLI / import

tooling). Where content-modeling concepts are mentioned, they exist only to help the agent

map the response shapes correctly.

---

0. How an AI agent should use this document

0. Detect language, framework, and data-access approach first (§0.1). Migrate in the same language and framework, and preserve the same data-access style (REST SDK → Delivery SDK; GraphQL → Contentstack GraphQL; raw fetch → raw fetch). Do not change paradigms. 1. Identify the Contentful surface in the target app. Search the codebase for from 'contentful', from 'contentful-management', createClient, getEntries, getEntry, getAssets, .fields., .sys., @contentful/rich-text-*, and image URLs on fields.file.url. Also search for GraphQL (graphql.contentful.com, gql, @apollo/client, urql, graphql-request, *.graphql) and Live Preview (preview.contentful.com, CPA token, @contentful/live-preview, draftMode). 2. Classify each call site using the mapping tables below (client init, read, query, reference resolution, rich text, asset/image, locale, pagination) — and the approach-specific sections (§17 GraphQL, §18 Live Preview, §19 raw REST / frameworks). 3. Rewrite each call site to the Contentstack equivalent, paying special attention to the response-shape differences (Section 6) — this is the single largest source of migration bugs. Contentful nests content under sys/fields; Contentstack flattens it. 4. Migrate rendering (rich text, images) using @contentstack/utils (Section 9–10). 5. Migrate Live Preview / draft mode (§18) if the source app implements it. 6. Verify against the gotchas (Section 13) and the checklist (Section 15).

0.1 Detect the data-access approach (decide the migration path)

A single app may use several of these at once (e.g. GraphQL for reads + Live Preview for the editor). Migrate each surface in kind.

Golden rule: Contentful and Contentstack are both API-first headless CMSs with a similar mental model (a space/stack contains content types, entries, and assets, published to environments). The migration is mostly mechanical if the response-shape and field-addressing differences are handled rigorously.

---

1. Package & import mapping

# remove
npm uninstall contentful contentful-management \
  @contentful/rich-text-html-renderer @contentful/rich-text-react-renderer @contentful/rich-text-types

# add
npm install @contentstack/delivery-sdk @contentstack/utils
# optional, only if cache policies are used:
npm install @contentstack/persistence-plugin

// Contentful
import { createClient } from 'contentful'

// Contentstack
import contentstack from '@contentstack/delivery-sdk'
import * as Utils from '@contentstack/utils'      // rich text, embedded items

A web app that reads content uses the Contentful CDA SDK (contentful). Some apps

also use contentful-management (CMA) for previews or editorial tooling. This document

focuses on the read path (CDA → Contentstack Delivery). The CMA query/entity model

(client.entry.getMany({ spaceId, environmentId, query })) shares the same query-operator

and data-model semantics described below.

---

2. Terminology mapping

---

3. Client initialization

Contentful (CDA)

import { createClient } from 'contentful'

const client = createClient({
  space: 'SPACE_ID',
  accessToken: 'CDA_TOKEN',
  environment: 'master',          // optional, defaults to 'master'
  host: 'cdn.contentful.com',     // 'preview.contentful.com' for CPA
})

Contentstack (Delivery)

import contentstack, { Region } from '@contentstack/delivery-sdk'

const stack = contentstack.stack({
  apiKey: 'API_KEY',              // was: space
  deliveryToken: 'DELIVERY_TOKEN',// was: accessToken
  environment: 'production',      // REQUIRED (no default)
  region: Region.US,              // US (default) | EU | AU | AZURE_NA | AZURE_EU | GCP_NA | GCP_EU
  locale: 'en-us',                // optional default locale
  // host: 'custom-cdn.example.com', // optional; overrides region host
  // branch: 'main',                 // optional branch
})

Key init differences (verified against `src/stack/contentstack.ts`):

• apiKey, deliveryToken, and `environment` are all required; the SDK throws on init if

any is missing. Contentful only requires space + accessToken.

• Region is a first-class enum. Don't hardcode hostnames unless you need a custom host.

Region → host: US → cdn.contentstack.io, EU → eu-cdn.contentstack.com, AU → au-cdn.contentstack.com, AZURE_NA → azure-na-cdn.contentstack.com, AZURE_EU → azure-eu-cdn.contentstack.com, GCP_NA → gcp-na-cdn.contentstack.com, GCP_EU → gcp-eu-cdn.contentstack.com.

• Preview: Contentful switches host to preview.contentful.com with a CPA token.

Contentstack uses a live_preview config object + stack.livePreviewQuery(...) instead.

• The Contentstack client is a builder: you start from stack.contentType(uid) /

stack.asset(uid) and chain. There is no flat client.getEntries(...).

---

4. Reading content — method mapping

Contentstack uses a fluent builder rooted at the stack. Calls terminate in .fetch() (single object) or .find() (collection/query).

Important: In Contentful, content_type is just a query parameter. In Contentstack,

the content type UID is part of the path (stack.contentType(uid)…). A single

Contentful getEntries call that mixed multiple content types must be split per content

type in Contentstack, or use the asset/entry query without a content type only for assets.

Canonical examples

// --- Single entry ---
// Contentful
const entry = await client.getEntry('blog123')
// Contentstack
const entry = await stack.contentType('blog_post').entry('blog123').fetch<BlogPost>()

// --- Collection ---
// Contentful
const res = await client.getEntries({ content_type: 'blog_post', limit: 10 })
res.items.forEach(...)
// Contentstack
const res = await stack.contentType('blog_post').entry().query().limit(10).find<BlogPost>()
res.entries?.forEach(...)

---

5. Query operator & modifier mapping

Contentful expresses queries as a flat params object with bracketed operators ('fields.price[gte]': 10). Contentstack uses a Query builder obtained via stack.contentType(uid).entry().query(), with explicit methods or the generic .where(fieldUid, QueryOperation.X, value).

Import the operator enums:

import { QueryOperation, QueryOperator } from '@contentstack/delivery-sdk'

5.1 Field comparison operators

Notes:

- Contentstack .where(field, QueryOperation.EQUALS, v) stores the bare value (no operator

wrapper), matching Contentful's bare 'fields.x': v.

- Contentstack has no direct equivalent to Contentful geo operators [near] / [within]

in the delivery builder; use .where()/.addParams() with the appropriate raw param if

geo querying is required.

- Contentful [all] (array contains all) has no first-class builder method; model with

$and of containedIn/equalTo or .addParams().

5.2 Logical combination

// Contentstack OR example
const q1 = stack.contentType('blog').entry().query().equalTo('category', 'news')
const q2 = stack.contentType('blog').entry().query().greaterThan('views', 1000)
const res = await stack.contentType('blog').entry().query().or(q1, q2).find<BlogPost>()

5.3 Sorting, pagination, field selection

Contentstack only/except use a BASE scope under the hood

(only[BASE][]=title); just pass field UIDs to the builder methods.

>

Placement (verified against source): .only() / .except() live on .entry() /

.entries() (and .asset()), not on the .query() object. Call them before .query():

stack.contentType(ct).entry().only(['title','slug']).query().find<T>(). Chaining

.query().only(...) will fail.

---

6. Response shape mapping (MOST IMPORTANT)

This is where most migration bugs originate. Contentful wraps content in `sys` + `fields`; Contentstack returns a flat entry object.

6.1 Single entry

Contentful:

{
  "sys": { "id": "blog123", "contentType": { "sys": { "id": "blogPost" } },
           "createdAt": "...", "updatedAt": "...", "locale": "en-US" },
  "fields": {                       // keyed by field id; flattened to one locale by default
    "title": "Hello",
    "slug": "hello",
    "author": { "sys": { "type": "Link", "linkType": "Entry", "id": "auth1" } }
  },
  "metadata": { "tags": [] }
}
// access: entry.fields.title, entry.sys.id, entry.sys.contentType.sys.id

Contentstack (verified against `BaseEntry` in `src/common/types.ts`):

{
  "uid": "blt...",                 // was sys.id
  "title": "Hello",                // fields are TOP-LEVEL, not under .fields
  "slug": "hello",
  "locale": "en-us",               // was sys.locale
  "created_at": "...",             // was sys.createdAt
  "updated_at": "...",             // was sys.updatedAt
  "_version": 3,
  "tags": [],
  "publish_details": { "environment": "...", "locale": "en-us", "time": "...", "user": "..." },
  "author": [ { /* resolved referenced entry */ } ]   // references are ARRAYS
}
// access: entry.title, entry.uid, entry.locale

6.2 Field address translation cheatsheet

6.3 Collection result

Contentstack find<T>() returns FindResponse<T>: { entries?: T[]; assets?: T[]; content_types?: TContentType[]; count?: number }. fetch<T>() returns the single object directly (the SDK unwraps response.entry / response.asset / response.content_type for you).

---

7. References / linked entries

Contentful auto-resolves links up to a depth using include (0–10, default 1) and returns unresolved links plus an includes sidecar that the SDK stitches into fields.

Contentstack does not resolve references by default. You must explicitly request each reference field by UID via includeReference. Resolved references appear inline as arrays on the entry.

// Contentful: depth-based
const res = await client.getEntries({ content_type: 'blog', include: 2 })
const authorName = res.items[0].fields.author.fields.name

// Contentstack: explicit, references resolve to arrays
const res = await stack.contentType('blog').entry().query()
  .includeReference('author', 'author.company')
  .find<BlogPost>()
const authorName = res.entries?.[0].author?.[0]?.name   // note the [0] — references are arrays

Migration pitfall: A single Contentful reference becomes a single-element array in

Contentstack. Code that did entry.fields.author.fields.name becomes

entry.author?.[0]?.name. Audit every dereference.

Related include modifiers (verified in entries.ts / entry.ts): includeContentType(), includeEmbeddedItems() (RTE embedded entries/assets), includeFallback() (locale fallback), includeMetadata(), includeBranch(), includeSchema().

---

8. Field-type mapping (for response handling)

Contentful field type values (verified in lib/entities/content-type-fields.ts) map to Contentstack data_type equivalents. Content modeling itself happens in the Contentstack UI / Management API; this table helps the agent reason about what a field will look like in the response and how to render it.

---

9. Rich text rendering

This is a substantial change. The JSON document shapes are different and the renderers are different. Contentful RichText is a @contentful/rich-text-types document; Contentstack uses JSON RTE (Supercharged RTE) rendered via @contentstack/utils.

// Contentful
import { documentToHtmlString } from '@contentful/rich-text-html-renderer'
const html = documentToHtmlString(entry.fields.body)

// Contentstack
import * as Utils from '@contentstack/utils'
const renderOption = {
  p:   (node, next) => `<p>${next(node.children)}</p>`,
  h1:  (node, next) => `<h1>${next(node.children)}</h1>`,
  bold:(text) => `<b>${text}</b>`,
  a:   (node) => {
    const txt = node.children.map((c) => c.text || '').join('')
    return `<a href="${node.attrs.url}">${txt}</a>`
  },
}
// For Supercharged/JSON RTE fields (MUTATES `entry` in place; returns void):
Utils.jsonToHTML({ entry, paths: ['body', 'group.rte_field'], renderOption })
// For HTML-RTE embedded items (fetch with .includeEmbeddedItems() first):
// NOTE: the option key is `paths` (plural string[]), NOT `path`. Also mutates `entry` in place.
Utils.render({ entry, paths: ['body'], renderOption })
// To render a raw RTE string/array and RECEIVE the HTML back (no mutation): Utils.renderContent(content, option)

Steps for the agent:

1. Add .includeEmbeddedItems() to any entry/entries fetch that renders RTE with embeds.

2. Replace documentToHtmlString(entry.fields.body) with

Utils.jsonToHTML({ entry, paths: ['body'], renderOption }) (note: it mutates/returns

HTML keyed onto the field path; pass the whole entry, not just the field value).

3. Translate renderNode/renderMark handlers into the renderOption shape.

---

10. Assets & image transformations

10.1 Asset shape

// Contentful
const url = 'https:' + asset.fields.file.url
// Contentstack
const url = asset.url

10.2 Image API / transforms

Both support URL-based image manipulation, but param names differ. Contentstack provides an ImageTransform builder (@contentstack/delivery-sdk) and a String.prototype.transform helper.

import { ImageTransform, Format } from '@contentstack/delivery-sdk'
const t = new ImageTransform().resize({ width: 300, height: 200 }).format(Format.WEBP).quality(80)
const optimized = asset.url.transform(t)   // String.prototype.transform helper (loaded by the SDK)

Caveat (verified in source): Format is a runtime value export, but at the package root

ImageTransform is currently re-exported type-only (export type { ImageTransform } in

index.ts). If new ImageTransform() from the package root fails at runtime, import the

value class from the assets module (the SDK's own tests use

import { ImageTransform } from '@contentstack/delivery-sdk/dist/.../assets'), or build the

transform URL by appending the documented image-delivery query params directly

(?width=300&height=200&format=webp&quality=80). The String.prototype.transform helper is

installed when the SDK is imported (import './common/string-extensions').

---

11. Locales / localization

Pitfall: With Contentful locale: '*', entry.fields.title becomes an object keyed by

locale. Apps relying on this multi-locale shape must be re-architected to query per locale

in Contentstack (Contentstack returns single-locale flat entries).

---

12. Pagination

// Contentstack offset pagination with total
const page = await stack.contentType('blog').entry().query()
  .includeCount().skip(20).limit(20).find<BlogPost>()
const total = page.count

---

13. Common gotchas / migration pitfalls

1. `.fields.` removal. Every entry.fields.X → entry.X. This is the most frequent edit. 2. `sys` → flat metadata. entry.sys.id → entry.uid; sys.createdAt → created_at; etc. 3. References become arrays. entry.fields.ref.fields.x → entry.ref?.[0]?.x. Even a single reference resolves to a one-element array. 4. References are not auto-resolved. Replace include: N with explicit .includeReference('field', 'field.nested'). Forgetting this leaves you with unresolved reference stubs ({ uid, _content_type_uid }). 5. Content type is in the path. No content_type query param; use stack.contentType(uid). Multi-type Contentful queries must be split per type. 6. `environment` is mandatory in Contentstack init (Contentful defaults to master). 7. Collection key rename. res.items → res.entries (or res.assets). res.total → res.count and only when .includeCount() is set. 8. `.find()` vs `.fetch()`. Collections/queries end in .find(); single objects end in .fetch(). Mixing them up is a common error. 9. Rich text is a different JSON dialect. You cannot pass a Contentful RichText document to @contentstack/utils; the underlying content must live in a Contentstack JSON RTE field. The renderer API also differs (tag-keyed renderOption vs BLOCKS/INLINES renderNode). 10. Locale casing. Lower-case all locale codes (en-US → en-us). 11. Asset URLs. Contentful URLs are often protocol-relative (//images.ctfassets.net/...) and need an added scheme; Contentstack URLs are absolute. 12. Image transform params differ. Don't carry over ?w=&h=&fit= query strings verbatim; rebuild with ImageTransform or the correct Contentstack image param names. 13. OR queries. Contentstack supports .or(...) natively; Contentful CDA often required multiple requests — you can consolidate during migration. 14. Typed responses. Pass an interface to fetch<T>() / find<T>(). Extend BaseEntry (from @contentstack/delivery-sdk) for entry types so uid, locale, created_at, etc. are typed. 15. `Utils.render` uses `paths` (plural array), not `path`. And jsonToHTML/render mutate the entry in place (return void) — pass the whole entry and read the field afterward; use Utils.renderContent(content, option) if you need a returned HTML string. 16. `@contentstack/utils` produces HTML strings, never components. Code using documentToReactComponents (a component tree) needs an HTML-injection strategy or a JSON-RTE→component serializer — not a 1:1 swap. 17. `ImageTransform` is type-only at the package root. new ImageTransform() from @contentstack/delivery-sdk may fail at runtime; build the image query string manually (?width=300&height=200&format=webp&quality=80) or deep-import the value class. 18. `stack.sync` keys are camelCase in TypeScript (paginationToken, syncToken), even though the response and some JSDoc examples use snake_case. 19. Match the data-access approach. Don't rewrite a GraphQL app to the REST SDK (or vice versa). GraphQL → Contentstack GraphQL (§17); preview → Contentstack Live Preview (§18).

---

14. Worked before/after example

Contentful (e.g. a Next.js / React data layer)

import { createClient } from 'contentful'
import { documentToHtmlString } from '@contentful/rich-text-html-renderer'

const client = createClient({
  space: process.env.CF_SPACE!,
  accessToken: process.env.CF_CDA_TOKEN!,
  environment: 'master',
})

export async function getPost(slug: string) {
  const res = await client.getEntries({
    content_type: 'blogPost',
    'fields.slug': slug,
    include: 2,
    limit: 1,
  })
  const post = res.items[0]
  return {
    title: post.fields.title,
    author: post.fields.author.fields.name,
    coverUrl: 'https:' + post.fields.coverImage.fields.file.url,
    bodyHtml: documentToHtmlString(post.fields.body),
  }
}

Contentstack (migrated)

import contentstack, { Region, BaseEntry } from '@contentstack/delivery-sdk'
import * as Utils from '@contentstack/utils'

const stack = contentstack.stack({
  apiKey: process.env.CS_API_KEY!,
  deliveryToken: process.env.CS_DELIVERY_TOKEN!,
  environment: process.env.CS_ENVIRONMENT!,   // required
  region: Region.US,
})

interface BlogPost extends BaseEntry {
  slug: string
  author: Array<{ name: string }>             // references resolve to arrays
  cover_image: { url: string }                // asset (file) field
  body: any                                   // JSON RTE
}

const renderOption = {
  p:    (node, next) => `<p>${next(node.children)}</p>`,
  bold: (text) => `<b>${text}</b>`,
}

export async function getPost(slug: string) {
  const res = await stack
    .contentType('blog_post')
    .entry()
    .query()
    .equalTo('slug', slug)
    .includeReference('author')               // explicit reference resolution
    .includeEmbeddedItems()                   // needed for RTE embeds
    .limit(1)
    .find<BlogPost>()

  const post = res.entries?.[0]
  if (!post) return null

  Utils.jsonToHTML({ entry: post, paths: ['body'], renderOption })  // mutates post.body → HTML

  return {
    title: post.title,                        // no .fields
    author: post.author?.[0]?.name,           // reference is an array
    coverUrl: post.cover_image?.url,          // absolute URL
    bodyHtml: post.body,                       // rendered by jsonToHTML
  }
}

---

15. Migration checklist (agent run order)

0. Detect language, framework, and data-access approach(es) (§0.1). Confirm prerequisites: the target stack already has the matching content model + published content, and you have a Contentful-field-ID → Contentstack-field-UID map. If reads are GraphQL, follow §17; if the app has Live Preview / draft mode, also follow §18. 1. Dependencies: remove contentful* + @contentful/rich-text-*; add @contentstack/delivery-sdk + @contentstack/utils (+ @contentstack/persistence-plugin only if cache policies are used). 2. Env vars: CF_SPACE/CF_CDA_TOKEN → CS_API_KEY/CS_DELIVERY_TOKEN/CS_ENVIRONMENT (+ region/branch as needed). 3. Client init: createClient(...) → contentstack.stack({...}). 4. Reads: rewrite each getEntry/getEntries/getAsset/getAssets/getContentType(s) to the builder form ending in .fetch()/.find() (§4). 5. Queries: translate every operator/sort/pagination/select param (§5). 6. References: replace include: N with explicit includeReference(...); convert single references to ?.[0] access (§7). 7. Field access: strip .fields.; map sys.* → flat metadata (uid, created_at, …) (§6). 8. Collections: res.items → res.entries/res.assets; res.total → .includeCount() + res.count. 9. Rich text: move RTE rendering to @contentstack/utils (jsonToHTML/render) with a renderOption; add .includeEmbeddedItems() where embeds are rendered (§9). 10. Assets/images: fields.file.url → url; rebuild image transforms with ImageTransform (§10). 11. Locales: lower-case codes; locale param → .locale(...); add .includeFallback() where Contentful relied on default-locale fallback (§11). 12. Types: introduce interfaces extending BaseEntry for fetch<T>()/find<T>(). 13. Verify: typecheck/build; smoke-test each migrated query against a real Contentstack stack; confirm reference arrays, RTE HTML output, and image URLs render correctly.

---

16. Quick API equivalence (condensed)

Contentful (contentful / CDA)                 Contentstack (@contentstack/delivery-sdk)
------------------------------------------     ---------------------------------------------------
createClient({ space, accessToken, env })  ->  contentstack.stack({ apiKey, deliveryToken, environment, region })
client.getEntry(id)                         ->  stack.contentType(ct).entry(id).fetch<T>()
client.getEntries({ content_type: ct })     ->  stack.contentType(ct).entry().query().find<T>()
client.getAsset(id)                         ->  stack.asset(id).fetch<T>()
client.getAssets(q)                         ->  stack.asset().query()...find<T>()
client.getContentType(id)                   ->  stack.contentType(id).fetch<T>()
client.getContentTypes()                    ->  stack.contentType().find<T>()
client.sync({ initial: true })              ->  stack.sync({ ... })
'fields.x': v                               ->  .equalTo('x', v) | .where('x', QueryOperation.EQUALS, v)
'fields.x[gte]': v                          ->  .greaterThanOrEqualTo('x', v)
order: '-fields.x'                          ->  .orderByDescending('x')
skip / limit                                ->  .skip(n) / .limit(m)
select: 'fields.a,fields.b'                 ->  .only(['a','b'])
include: N                                  ->  .includeReference('a','a.b')
res.items / res.total                       ->  res.entries / (res.count via .includeCount())
entry.fields.x / entry.sys.id               ->  entry.x / entry.uid
documentToHtmlString(entry.fields.body)     ->  Utils.jsonToHTML({ entry, paths:['body'], renderOption })
asset.fields.file.url                       ->  asset.url

---

17. GraphQL migration (Contentful GraphQL → Contentstack GraphQL)

If the app reads via the Contentful GraphQL Content API (signals: graphql.contentful.com, gql tagged templates, *.graphql files, @apollo/client / urql / graphql-request, GraphQL Code Generator), migrate to the Contentstack GraphQL Content Delivery API — do not rewrite it to the REST Delivery SDK. Keep the same GraphQL client library; only the endpoint, auth, schema, and query/fragment text change. The response-shape principles in §6 still apply (flattened fields, uid/created_at metadata, references as nested objects).

The Contentstack GraphQL API is a separate service and is not part of @contentstack/delivery-sdk.

The endpoint hosts, header names, and pagination/filter argument names below should be **verified

against current Contentstack GraphQL documentation** for the target region before finalizing.

17.1 Endpoint & auth

17.2 Query shape

Field/type names follow the Contentstack content-type & field UIDs (snake_case, e.g. blog_post, cover_image), not Contentful's camelCase ids.

# Contentful
query {
  blogPostCollection(limit: 10, where: { slug: "hello" }) {
    total
    items { title slug author { name } }
  }
}

# Contentstack (verify exact arg/field names against the stack's GraphQL schema)
query {
  all_blog_post(limit: 10, where: { slug: "hello" }) {
    total
    items {
      title
      slug
      author { ... on SysAssetOrEntry { /* reference: nest the referenced type's fields */ } }
    }
  }
}

17.3 Steps for the agent

1. Repoint the GraphQL client (Apollo/urql/graphql-request) at the Contentstack endpoint and swap Authorization: Bearer → access_token header + environment query param. 2. Rewrite every query/fragment to the Contentstack schema (collection names, field UIDs, reference nesting, filter args, lower-cased locales). 3. Update response handling for the new shape (items arrays, flat fields, uid/created_at). 4. If GraphQL Code Generator is used, repoint it at the Contentstack schema/introspection and regenerate types; fix call sites against the new generated types. 5. Render RTE/JSON fields with @contentstack/utils (§9), same as the REST path.

---

18. Live Preview / draft mode migration

If the source app implements Contentful Preview or Live Preview, reimplement equivalent behavior with Contentstack Live Preview, matching the source's scope (which routes/components, SSR vs client, click-to-edit vs. read-only preview).

Detect in the source: host: 'preview.contentful.com', a CPA / Content Preview token, a second "preview" client, @contentful/live-preview (ContentfulLivePreview.init, useContentfulLiveUpdates, useContentfulInspectorMode), Next.js draftMode() / preview API routes, or a ?preview= route gate.

18.1 SDK config & per-request hash (verified against @contentstack/delivery-sdk source)

live_preview is a first-class field on StackConfig (src/common/types.ts), and the stack exposes livePreviewQuery(...):

const stack = contentstack.stack({
  apiKey: process.env.CS_API_KEY!,
  deliveryToken: process.env.CS_DELIVERY_TOKEN!,
  environment: process.env.CS_ENVIRONMENT!,
  live_preview: {
    enable: true,                         // REQUIRED on the LivePreview type
    preview_token: process.env.CS_PREVIEW_TOKEN!,  // preferred (management_token is legacy)
    host: 'rest-preview.contentstack.com',// regional preview host (verify per region)
  },
})

// Per request, apply the preview hash (from the URL / live-preview-utils) before fetching:
stack.livePreviewQuery({
  live_preview: hash,            // the live_preview hash for the edited entry
  contentTypeUid: 'blog_post',   // also accepts content_type_uid
  entryUid: 'blt...',            // also accepts entry_uid
  // preview_timestamp, release_id, include_applied_variants are also supported
})

LivePreview type fields (verified): enable: boolean (required), preview_token?, management_token? (legacy), host?, live_preview?, contentTypeUid?, entryUid?, include_applied_variants?. In the browser, the SDK auto-reads live_preview, release_id, and preview_timestamp from the page URL's query string during stack(...) init.

18.2 Front-end real-time updates & click-to-edit (@contentstack/live-preview-utils)

Not part of the Delivery SDK and not vendored in this workspace — verify the exact API against

current @contentstack/live-preview-utils docs. Add it as a dependency.

18.3 Steps for the agent

1. Add live_preview to the stack init (enable: true + preview_token + regional preview host). 2. Add @contentstack/live-preview-utils; call ContentstackLivePreview.init(...) where the source called ContentfulLivePreview.init(...). 3. Replace the source's live-update hook with onEntryChange(...) re-fetching, calling stack.livePreviewQuery({ live_preview, contentTypeUid, entryUid }) before each preview fetch. 4. If the source had click-to-edit (inspector mode), add Utils.addEditableTags(...) and render the resulting data-cslp attributes on the same elements. 5. Preserve the existing preview gating/routing (e.g. Next.js draftMode, ?preview= guard); only swap the backend. Keep preview tokens server-side.

---

19. Raw REST / fetch and framework source plugins

Not every app uses an SDK. Migrate these in kind:

• Raw `fetch`/`axios` to `cdn.contentful.com`. Repoint to the Contentstack Content Delivery

REST API: base https://{region-cdn-host}/v3 (US cdn.contentstack.io; see §3 for regional hosts), headers api_key, access_token, and environment as a query param. Endpoints: /v3/content_types/{ct_uid}/entries (list), /v3/content_types/{ct_uid}/entries/{uid} (single), /v3/assets. Query params map per §5 (include[]=author, only[BASE][]=title, limit, skip, include_count=true, locale, include_fallback=true). Response keys per §6 (entries/entry, assets/asset, count). Prefer adopting @contentstack/delivery-sdk if it doesn't fight the app's architecture, but a like-for-like raw-fetch migration is valid.

• Gatsby (`gatsby-source-contentful`). Migrate to @contentstack/gatsby-source-contentstack:

swap the plugin + its options (api_key, delivery_token, environment, regions) in gatsby-config, and rewrite GraphQL queries from allContentfulXxx to the Contentstack source plugin's node types (verify node-type naming against the plugin docs).

• Framework data-fetching idioms — keep them. Migrate the data-layer call inside the app's

existing pattern; don't change where/how data is fetched:

• Next.js: getStaticProps/getServerSideProps/generateStaticParams/RSC fetch — keep the

same function, swap the client call. Keep ISR/caching tags.

• Remix loader, SvelteKit load, Nuxt useAsyncData/asyncData, Vue composables, Angular

services/resolvers — same: swap only the CMS call body.

• Module-singleton vs per-request client: instantiate the Contentstack stack the same way the

Contentful client was instantiated (one shared client module is the common case).