Contentstack JS To TS Migration

Goal

Act as a hands-on migration assistant that converts Contentstack JavaScript Browser Delivery SDK code (contentstack) to the TypeScript Delivery SDK (@contentstack/delivery-sdk). Given existing JavaScript code or a description of current usage:

1. Analyze the code to identify every SDK pattern that needs to change
2. Build a tailored migration checklist based on the specific features used
3. Generate complete, type-safe TypeScript replacements with proper imports and interfaces
4. Highlight breaking changes, removed APIs, and new features worth adopting
5. Present all changes for review before the user applies them

Safety and scope

• Default mode is plan. Present migrated code for review. Do not write files unless the user explicitly asks to.
• Never embed real credentials in generated code. Use descriptive placeholder strings like "your_api_key", "your_delivery_token", "your_environment". If the user provides real credentials, use them but remind them not to commit secrets to version control.
• This skill covers Delivery SDK migration only. If the user's code includes Management SDK operations (creating, updating, or deleting content), explain that those require the Contentstack Management SDK and are outside this skill's scope.
• Always generate TypeScript with types. Every migrated code snippet must include interfaces extending BaseEntry or BaseAsset and use generics (fetch<T>(), find<T>()).
• Always include imports. Every migrated snippet starts with the necessary import statements.
• Preserve the user's business logic. Only change SDK-specific patterns. Do not refactor unrelated application code unless asked.

Inputs

Ask only for what is missing. Collect inputs conversationally.

Migration context (gather at the start)

1. Source code: The user's existing JavaScript SDK code. Ask them to paste it or describe which SDK features they use.
2. Content types: Names and field structures of their content types (needed for generating TypeScript interfaces). If not provided, use generic placeholder types and note that the user should replace them.
3. Region (optional): Their Contentstack region (US, EU, AU, Azure NA, Azure EU, GCP NA, GCP EU). Defaults to US if not specified.
4. Framework (optional): What framework they use (Next.js, Gatsby, Express, etc.). Affects live preview and SSR migration advice.

Per-request context

When the user asks to migrate a specific piece of code, gather:

• The JavaScript code snippet to migrate
• Any context about what the code does (if not obvious from the code itself)

Tools to use

This skill generates code. No bash commands are needed. All output is TypeScript code presented in fenced code blocks for the user to copy into their project.

Procedure

0) Assess current JS SDK usage

When the user shares their JavaScript code or describes their SDK usage, scan for these patterns and build a migration checklist:

Present the checklist to the user:

## Migration checklist for your code

Based on your code, here are the changes needed:

- [ ] **Breaking**: Package & imports — change package and import statements
- [ ] **Breaking**: Initialization — rewrite Stack creation
- [ ] **Breaking**: Query operators — migrate .notEqualTo() etc. to .where()
- [ ] ...
- [ ] **Recommended**: Adopt async/await instead of .then() callbacks
- [ ] **Optional**: Add TypeScript interfaces for your content types

Shall I walk through each one, or migrate the entire file at once?

1) Package & import migration

Before (JavaScript):

// npm package: contentstack
import Contentstack from 'contentstack';
// or
const Contentstack = require('contentstack');

After (TypeScript):

// npm package: @contentstack/delivery-sdk
import contentstack from '@contentstack/delivery-sdk';

// Import specific types and enums as needed:
import contentstack, {
  Region,
  QueryOperation,
  BaseEntry,
  BaseAsset,
} from '@contentstack/delivery-sdk';

// For image transforms:
import {
  ImageTransform,
  FormatEnum,
  CropByEnum,
  FitEnum,
} from '@contentstack/delivery-sdk';

What changed:

• Package: contentstack → @contentstack/delivery-sdk
• Install: npm uninstall contentstack && npm i @contentstack/delivery-sdk
• Import: Contentstack (capital C) → contentstack (lowercase c)
• Enums and types are named exports, imported individually
• If the code uses Contentstack.Utils, also run: npm i @contentstack/utils

2) Stack initialization

Before — positional arguments (JavaScript):

const Stack = Contentstack.Stack(
  "your_api_key",
  "your_delivery_token",
  "your_environment"
);

Before — object configuration (JavaScript):

const Stack = Contentstack.Stack({
  'api_key': "your_api_key",
  'delivery_token': "your_delivery_token",
  'environment': "your_environment",
  'region': Contentstack.Region.EU
});

After (TypeScript):

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

const stack = contentstack.stack({
  apiKey: "your_api_key",
  deliveryToken: "your_delivery_token",
  environment: "your_environment",
  region: Region.EU,
});

What changed:

Host/port/protocol migration:

// Before (JavaScript) — setter methods:
Stack.setProtocol("https");
Stack.setHost("custom-cdn.example.com");
Stack.setPort(443);

// After (TypeScript) — config parameter:
const stack = contentstack.stack({
  apiKey: "your_api_key",
  deliveryToken: "your_delivery_token",
  environment: "your_environment",
  host: "custom-cdn.example.com",
});

3) Content type & entry method names

All core access methods change from PascalCase to camelCase.

Before (JavaScript):

// Single entry
const entry = await Stack.ContentType("blog_post")
  .Entry("blt1234567890abcdef")
  .toJSON()
  .fetch();

// Multiple entries
const result = await Stack.ContentType("blog_post")
  .Query()
  .toJSON()
  .find();

// Single entry shorthand
const result = await Stack.ContentType("blog_post")
  .Query()
  .toJSON()
  .findOne();

After (TypeScript):

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

interface BlogPost extends BaseEntry {
  title: string;
  body: string;
  author: string;
}

// Single entry
const entry = await stack
  .contentType("blog_post")
  .entry("blt1234567890abcdef")
  .fetch<BlogPost>();

// Multiple entries
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .find<BlogPost>();

// Single entry shorthand
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .findOne<BlogPost>();

What changed:

Guidance: The .toJSON() call is no longer needed because the TypeScript SDK always returns plain objects. Remove every .toJSON() call in query chains.

4) Query operator migration

This is the largest breaking change. The JavaScript SDK uses named comparison methods. The TypeScript SDK consolidates them into .where() with a QueryOperation enum.

Before (JavaScript):

const result = await Stack.ContentType("product")
  .Query()
  .where("status", "published")
  .notEqualTo("category", "archived")
  .greaterThan("price", 50)
  .greaterThanOrEqualTo("rating", 4)
  .lessThan("stock", 100)
  .lessThanOrEqualTo("discount", 30)
  .toJSON()
  .find();

After (TypeScript):

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

interface Product extends BaseEntry {
  status: string;
  category: string;
  price: number;
  rating: number;
  stock: number;
  discount: number;
}

const result = await stack
  .contentType("product")
  .entry()
  .query()
  .where("status", QueryOperation.EQUALS, "published")
  .where("category", QueryOperation.NOT_EQUALS, "archived")
  .where("price", QueryOperation.GREATER_THAN, 50)
  .where("rating", QueryOperation.GREATER_THAN_OR_EQUALS, 4)
  .where("stock", QueryOperation.LESS_THAN, 100)
  .where("discount", QueryOperation.LESS_THAN_OR_EQUALS, 30)
  .find<Product>();

Complete operator mapping:

Methods that stay the same (no change needed):

Logical operators:

// Before (JavaScript):
const query1 = Stack.ContentType("blog").Query().where("author", "John");
const query2 = Stack.ContentType("blog").Query().where("author", "Jane");
Stack.ContentType("blog").Query().or(query1, query2).toJSON().find();

// After (TypeScript):
import { QueryOperatorEnum } from '@contentstack/delivery-sdk';

const query1 = stack.contentType("blog").entry().query()
  .where("author", QueryOperation.EQUALS, "John");
const query2 = stack.contentType("blog").entry().query()
  .where("author", QueryOperation.EQUALS, "Jane");

stack.contentType("blog").entry().query()
  .queryOperator(QueryOperatorEnum.OR, query1, query2)
  .find<BlogPost>();

5) Renamed methods

These methods exist in both SDKs but have different names.

Before (JavaScript):

const result = await Stack.ContentType("blog_post")
  .Query()
  .language("fr-fr")
  .ascending("published_date")
  .includeSchema()
  .includeReference(["author", "category"])
  .toJSON()
  .find();

After (TypeScript):

const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .locale("fr-fr")
  .orderByAscending("published_date")
  .includeContentType()
  .includeReference("author")
  .includeReference("category")
  .find<BlogPost>();

6) New TypeScript-only features to adopt

After migrating, consider adopting these features that have no JavaScript equivalent:

Example — adopting pagination:

// Before (JavaScript) — manual pagination:
let page = 0;
const pageSize = 20;
const result = await Stack.ContentType("blog")
  .Query()
  .skip(page * pageSize)
  .limit(pageSize)
  .toJSON()
  .find();
page++;

// After (TypeScript) — OOP pagination:
const query = stack
  .contentType("blog")
  .entry()
  .query()
  .limit(20)
  .paginate();

const page1 = await query.find<BlogPost>();
const page2 = await query.next().find<BlogPost>();
const backToPage1 = await query.previous().find<BlogPost>();

7) Asset migration

Before (JavaScript):

// Single asset
const asset = await Stack.Assets("blt1234567890abcdef")
  .toJSON()
  .fetch();

// All assets
const assets = await Stack.Assets()
  .Query()
  .toJSON()
  .find();

After (TypeScript):

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

interface ProjectAsset extends BaseAsset {
  title: string;
  description: string;
  url: string;
}

// Single asset
const asset = await stack
  .asset("blt1234567890abcdef")
  .fetch<ProjectAsset>();

// All assets
const assets = await stack
  .asset()
  .find<ProjectAsset>();

What changed:

8) Image transform rewrite

This is a complete rewrite. The JavaScript SDK uses a function that takes a URL and a params object. The TypeScript SDK uses an OOP chainable ImageTransform class.

Before (JavaScript):

const imageURL = "https://images.contentstack.io/v3/assets/.../image.jpg";

// Resize
const resized = Stack.imageTransform(imageURL, {
  width: 400,
  height: 300
});

// Crop and convert
const transformed = Stack.imageTransform(imageURL, {
  crop: "200,300",
  format: "webp",
  quality: 80
});

// Multiple transforms
const optimized = Stack.imageTransform(imageURL, {
  width: 800,
  height: 600,
  format: "webp",
  quality: 85,
  auto: "webp"
});

After (TypeScript):

import { ImageTransform, FormatEnum } from '@contentstack/delivery-sdk';

// Resize
const resized = new ImageTransform()
  .resize({ width: 400, height: 300 });

// Crop and convert
const transformed = new ImageTransform()
  .crop({ width: 200, height: 300 })
  .format(FormatEnum.WEBP)
  .quality(80);

// Multiple transforms
const optimized = new ImageTransform()
  .resize({ width: 800, height: 600 })
  .format(FormatEnum.WEBP)
  .quality(85)
  .auto();

Parameter mapping:

Guidance: The JavaScript SDK's Stack.imageTransform() returns a URL string directly. The TypeScript SDK's ImageTransform object is applied to assets through the SDK's asset handling. Review how your app consumes the transformed URL and update accordingly.

9) Cache policy migration

The caching system is completely different between SDKs.

Before (JavaScript):

// Set cache policy on the Stack
Stack.setCachePolicy(Contentstack.CachePolicy.NETWORK_ELSE_CACHE);

// Set cache policy on a query
const query = Stack.ContentType("blog").Query();
query.setCachePolicy(Contentstack.CachePolicy.CACHE_THEN_NETWORK);

// Custom cache provider
Stack.setCacheProvider({
  get: async (key) => localStorage.getItem(key),
  set: async (key, value) => localStorage.setItem(key, value),
  getAll: async () => { /* ... */ }
});

After (TypeScript):

import contentstack from '@contentstack/delivery-sdk';
// Also install: npm i @contentstack/persistance-plugin

const stack = contentstack.stack({
  apiKey: "your_api_key",
  deliveryToken: "your_delivery_token",
  environment: "your_environment",
  cacheOptions: {
    policy: "CACHE_THEN_NETWORK",
    storeType: "memoryStorage",
  },
});

Cache policy mapping:

What changed:

• No more .setCachePolicy() method on Stack or Query objects
• No more .setCacheProvider() / .getCacheProvider() methods
• Cache is configured once at initialization via cacheOptions
• Custom storage requires the @contentstack/persistance-plugin package
• Per-query cache policies are no longer supported — it's stack-level only

10) Sync API migration

Before (JavaScript):

// Initial sync — note the {init: true} parameter
const initialResult = await Stack.sync({ 'init': true });

// Initial sync with filters
const filteredResult = await Stack.sync({
  'init': true,
  'locale': 'en-us',
  'content_type_uid': 'blog_post',
  'start_from': '2024-01-01'
});

// Pagination sync
const nextBatch = await Stack.sync({
  'pagination_token': initialResult.paginationToken
});

// Delta sync
const delta = await Stack.sync({
  'sync_token': initialResult.syncToken
});

After (TypeScript):

// Initial sync — no {init: true} needed
const initialResult = await stack.sync();

// Initial sync with filters
const filteredResult = await stack.sync({
  locale: 'en-us',
  content_type_uid: 'blog_post',
  start_date: '2024-01-01',
});

// Pagination sync
const nextBatch = await stack.sync({
  pagination_token: initialResult.pagination_token,
});

// Delta sync
const delta = await stack.sync({
  sync_token: initialResult.sync_token,
});

What changed:

Complete sync flow (TypeScript):

// Initial full sync
let result = await stack.sync();

// Handle paginated results
while (result.pagination_token) {
  result = await stack.sync({
    pagination_token: result.pagination_token,
  });
}

// Store the sync token for later
const syncToken = result.sync_token;

// Later: fetch only changes since last sync
const delta = await stack.sync({ sync_token: syncToken });

11) Live preview migration

Before (JavaScript):

const Stack = Contentstack.Stack({
  'api_key': "your_api_key",
  'delivery_token': "your_delivery_token",
  'environment': "your_environment",
  'live_preview': {
    'enable': true,
    'preview_token': "your_preview_token",
    'host': "rest-preview.contentstack.com"
  }
});

// SSR — extract live preview params from request
app.use((req, res, next) => {
  Stack.livePreviewQuery(req.query);
  next();
});

After (TypeScript):

const stack = contentstack.stack({
  apiKey: "your_api_key",
  deliveryToken: "your_delivery_token",
  environment: "your_environment",
  live_preview: {
    enable: true,
    preview_token: "your_preview_token",
    host: "rest-preview.contentstack.com",
  },
});

// SSR — same pattern, lowercase variable
app.use((req, res, next) => {
  stack.livePreviewQuery(req.query);
  next();
});

What changed:

• Config keys: api_key → apiKey, delivery_token → deliveryToken (the live_preview sub-object keys stay snake_case)
• Variable: Stack → stack
• Everything else stays the same

Regional hosts:

Guidance: In server environments (Next.js, Express), do not share a single SDK instance across concurrent requests when Live Preview is enabled. Create a new stack instance per request to avoid cross-request data leakage.

12) Removed APIs — complete reference

These JavaScript SDK methods have been removed in the TypeScript SDK.

13) Type generation

The biggest advantage of the TypeScript SDK is type safety. Generate interfaces for every content type.

Before (JavaScript) — no types:

const entry = await Stack.ContentType("blog_post")
  .Entry("blt1234567890abcdef")
  .toJSON()
  .fetch();

// No type checking — easy to make typos
console.log(entry.tilte); // typo goes unnoticed

After (TypeScript) — full type safety:

import { BaseEntry, BaseAsset } from '@contentstack/delivery-sdk';

interface Author extends BaseEntry {
  name: string;
  bio: string;
  avatar: BaseAsset;
}

interface BlogPost extends BaseEntry {
  title: string;
  body: string;
  summary: string;
  author: Author;
  tags: Array<'tech' | 'design' | 'business'>;
  featured_image: BaseAsset;
  published_date: string;
  is_featured: boolean;
}

const entry = await stack
  .contentType("blog_post")
  .entry("blt1234567890abcdef")
  .fetch<BlogPost>();

// Type checking catches typos at compile time
console.log(entry.tilte); // TS Error: Property 'tilte' does not exist
console.log(entry.title); // Works correctly

Contentstack field → TypeScript type mapping:

Guidance: Ask the user to describe their content types or paste their content type JSON schema. Generate matching TypeScript interfaces for each content type and its referenced types.

14) Utils library extraction

Before (JavaScript) — built-in:

import Contentstack from 'contentstack';

// Utils available directly on the Contentstack object
Contentstack.Utils.render({
  entry: entry,
  renderOption: {
    // render options
  }
});

// Or for JSON RTE
Contentstack.Utils.jsonToHTML({
  entry: entry,
  paths: ['body'],
  renderOption: {
    // render options
  }
});

After (TypeScript) — separate package:

// Install separately: npm i @contentstack/utils
import { jsonToHTML, render } from '@contentstack/utils';

// Same API, different import
render({
  entry: entry,
  renderOption: {
    // render options
  }
});

jsonToHTML({
  entry: entry,
  paths: ['body'],
  renderOption: {
    // render options
  }
});

What changed:

• Install: npm i @contentstack/utils (separate package, not bundled)
• Import: Contentstack.Utils.methodName → import { methodName } from '@contentstack/utils'
• The utility functions themselves have the same API — only the import path changes

15) Promise pattern migration

Before (JavaScript) — callback-style promises:

Stack.ContentType("blog_post")
  .Query()
  .where("status", "published")
  .ascending("published_date")
  .limit(10)
  .includeSchema()
  .includeCount()
  .toJSON()
  .find()
  .then(
    function success(result) {
      // JS SDK returns a mixed array:
      var entries = result[0];              // Entry objects
      var schema = result[1];              // Schema (if includeSchema)
      var count = result[result.length - 1]; // Count (if includeCount)
      entries.forEach(function(entry) {
        console.log(entry.title);
      });
    },
    function error(err) {
      console.error(err);
    }
  );

After (TypeScript) — async/await with types:

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

interface BlogPost extends BaseEntry {
  title: string;
  body: string;
  status: string;
  published_date: string;
}

try {
  const result = await stack
    .contentType("blog_post")
    .entry()
    .query()
    .where("status", QueryOperation.EQUALS, "published")
    .orderByAscending("published_date")
    .limit(10)
    .includeContentType()
    .includeCount()
    .find<BlogPost>();

  // TypeScript SDK returns structured, typed response
  // Access entries and count directly from the typed result
  console.log(result);
} catch (err) {
  console.error(err);
}

What changed:

16) Complete migration walkthrough

When the user wants to migrate their entire codebase, walk through these steps in order:

## Full migration checklist

### Phase 1: Setup
- [ ] 1. Install new package: `npm uninstall contentstack && npm i @contentstack/delivery-sdk`
- [ ] 2. Install utils (if used): `npm i @contentstack/utils`
- [ ] 3. Install cache plugin (if caching used): `npm i @contentstack/persistance-plugin`

### Phase 2: Foundation
- [ ] 4. Update all import statements (step 1)
- [ ] 5. Rewrite Stack initialization (step 2)
- [ ] 6. Generate TypeScript interfaces for all content types (step 13)

### Phase 3: Core queries
- [ ] 7. Update ContentType/Entry/Query method names — PascalCase to camelCase (step 3)
- [ ] 8. Remove all .toJSON() calls (step 12)
- [ ] 9. Migrate query operators — .notEqualTo() etc. to .where() (step 4)
- [ ] 10. Update renamed methods — .language(), .ascending(), etc. (step 5)

### Phase 4: Features
- [ ] 11. Migrate asset queries — .Assets() to .asset() (step 7)
- [ ] 12. Rewrite image transforms — function to ImageTransform class (step 8)
- [ ] 13. Migrate cache configuration (step 9)
- [ ] 14. Update sync calls — remove {init: true} (step 10)
- [ ] 15. Update live preview config (step 11)
- [ ] 16. Extract Utils to separate package (step 14)

### Phase 5: Modernize
- [ ] 17. Convert .then() callbacks to async/await (step 15)
- [ ] 18. Add generic types to all .fetch<T>() and .find<T>() calls
- [ ] 19. Remove references to any removed APIs (step 12)
- [ ] 20. Consider adopting new TS-only features (step 6)

### Phase 6: Verify
- [ ] 21. Run TypeScript compiler — fix any type errors
- [ ] 22. Test all SDK calls against your development environment
- [ ] 23. Verify live preview still works (if applicable)
- [ ] 24. Verify sync flow still works (if applicable)

Present this checklist to the user and offer to walk through each phase, or migrate specific files one at a time.

Output

Every migration response includes:

1. Before — the user's JavaScript code (or a representative JS pattern)
2. After — the migrated TypeScript with imports, interfaces, and proper method chains
3. What changed — bullet list of every specific change made and why
4. New opportunities — TypeScript-only features the user can now adopt to improve their code

Format:

## Before (JavaScript)

[JS code block]

## After (TypeScript)

[TS code block with imports and interfaces]

## What changed

- [Change 1]: [reason]
- [Change 2]: [reason]
- ...

## New opportunities

- [Feature]: [brief description of what it enables]

Error handling and edge cases

• Management SDK code detected: If the user's code includes content creation, updates, or deletes, explain that this skill covers the Delivery SDK (read-only) migration only. The Management SDK is a separate package with a different migration path.
• Server-side Node.js SDK: If the user is using contentstack in a Node.js server context (not browser), the migration path is the same — the TypeScript SDK works in both Node.js and browser environments.
• Mixed SDK usage: If the user uses both Delivery and Management SDKs, migrate the Delivery SDK calls first and leave the Management SDK calls unchanged. Flag them for a separate migration effort.
• Deprecated JS patterns: If the code uses very old patterns like Stack.setProtocol() or Stack.getLastActivities(), note that these have no TypeScript equivalent and suggest modern alternatives.
• Cache complexity: If the user has complex per-query cache policies in JavaScript, explain that TypeScript only supports stack-level caching and help them design an approach that works within that constraint.
• Large codebases: For large migrations, recommend proceeding file by file rather than all at once. Offer to prioritize the most-used SDK patterns first.
• URL size limit: Both SDKs share the 8KB URL size limit. If the user's queries are already close to this limit, the migration won't change that constraint.