# Why migrate, and what actually changes

- **Authors:** Tim Benniks
- **Published:** 2026-04-27T10:03:10.446Z
- **Updated:** 2026-04-27T10:03:56.154Z
- **Tags:** sdk, api

---

Moving from the JavaScript Delivery SDK to the TypeScript Delivery SDK is best treated as a careful delivery-layer upgrade. Your Contentstack stack, content types, entries, assets, environments, locales, and delivery tokens do not need to change just because the SDK package changes.

The code that talks to Contentstack does change. Most of the work is updating how you create the stack client and how you build requests for entries, assets, content types, sync, and queries.

## What you'll learn

- What the TypeScript Delivery SDK changes in day-to-day development


- What does not need to change in your Contentstack stack


- Why the migration is safer when you isolate SDK calls first


- Which parts of the old JavaScript SDK map directly to the new SDK


- Where the migration needs extra attention



## The migration in practical terms

The JavaScript Delivery SDK commonly uses uppercase builders:

```javascript
import contentstack from 'contentstack';

const Stack = contentstack.Stack({
  apiKey: process.env.CONTENTSTACK_API_KEY,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN,
  environment: process.env.CONTENTSTACK_ENVIRONMENT,
});

const result = await Stack.ContentType('blog')
  .Entry('entry_uid')
  .toJSON()
  .fetch();
```

The TypeScript Delivery SDK uses the @contentstack/delivery-sdk package and lowercase builders:

```javascript
import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN,
  environment: process.env.CONTENTSTACK_ENVIRONMENT,
});

const result = await stack.contentType('blog')
  .entry('entry_uid')
  .fetch();
```

The change is not just capitalization. The newer SDK has different package boundaries, different method names for some query operations, and optional TypeScript generics for teams that want typed response shapes.

## What does not change

Your content model stays the same. A blog content type is still a blog content type. An entry UID is still an entry UID. A delivery token still reads published content from an environment. Locale and fallback behavior still depend on what your stack has published.

In most migrations, these things do not need to change:

- stack API key


- delivery token


- environment name


- branch strategy


- locale strategy


- content type UIDs


- entry UIDs


- asset UIDs


- reference field UIDs


- frontend routes



If your app already has good separation between Contentstack fetch logic and rendering components, the migration can stay small. If SDK calls are scattered across pages, components, route handlers, and helper files, start by collecting the most common calls behind a small wrapper.

## What changes

The most visible changes are:

- contentstack becomes @contentstack/delivery-sdk


- contentstack.Stack() becomes contentstack.stack()


- Stack.ContentType() becomes stack.contentType()


- Entry() becomes entry()


- Assets() or Asset() becomes asset()


- Query() becomes entry().query() for entry queries


- language() becomes locale()


- ascending() and descending() become orderByAscending() and orderByDescending()


- toJSON() is usually removed because fetch() and find() return data directly


- cache persistence moves into @contentstack/persistance-plugin


- rich text and other utility helpers move into @contentstack/utils



Those changes are mechanical, but they are still worth doing in small batches so you can compare responses as you go.

## A good migration shape

Start with the file that creates your Contentstack client. Then migrate one read path at a time.

A useful order is:

- Install the new SDK and create a new stack client.


- Convert single-entry reads.


- Convert entry collection queries.


- Convert asset reads.


- Convert content type reads.


- Convert sync calls.


- Add caching and utility packages only if your current app uses those behaviors.


- Run the same pages or tests against old and new responses before deleting the old package.



This keeps the migration observable. A delivery SDK sits close to production content, so it is better to make a few boring changes and verify them than to do one large invisible rewrite.

## Where to be careful

Be careful around code that assumes a specific response shape. If a component expects the old SDK's transformed JSON, compare the old response and the new response before changing rendering logic.

Also check any custom query helpers. Method names such as includeReference, includeCount, only, except, skip, and limit still exist, but their placement in the chain may change depending on whether you are fetching a single entry, an entry collection, or a query object.

## Key takeaways

- This is an SDK migration, not a mandatory TypeScript rewrite.


- The Contentstack content model and published content do not need to change.


- Most code changes are package, initialization, and method-chain updates.


- Migrate through a small Contentstack wrapper when possible.


- Compare old and new responses around high-traffic pages before removing the JavaScript SDK.






---

## Frequently asked questions

### Do I need to change my Contentstack stack, content types, or entries when migrating SDKs?

No. Your stack configuration and content model stay the same; the migration is primarily code changes in your delivery layer.

### What are the most common API changes between the JavaScript and TypeScript Delivery SDKs?

The package changes to @contentstack/delivery-sdk, builders move from uppercase to lowercase, and several methods are renamed or repositioned in the chain.

### Is migrating to the TypeScript Delivery SDK the same as rewriting my app in TypeScript?

No. You can use the TypeScript Delivery SDK without converting your codebase to TypeScript; generics are optional.

### What is a safe order to migrate SDK usage in an existing app?

Start with client initialization, then migrate single-entry reads, collection queries, assets, content types, and sync calls, validating responses as you go.

### Where should I be careful during the migration?

Be careful with code that assumes specific response shapes and with custom query helpers, since method placement can differ between entry, collection, and query chains.



---

## Chapter Navigation

**← Previous:** [Migrating from the JavaScript Delivery SDK to the TypeScript Delivery SDK](https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk)

**Next →:** [Install and initialize the TypeScript Delivery SDK](https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk/install-and-initialize-the-typescript-delivery-sdk)