# Migrating from the JavaScript Delivery SDK to the TypeScript Delivery SDK

- **Authors:** Tim Benniks
- **Published:** 2026-04-27
- **Updated:** 2026-04-27T10:14:31.619Z
- **Tags:** sdk, api

---

> **Full guide available:** [View all 8 chapters in one document](https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk/full.md)

## What this guide is for

This guide is for developers who already use the Contentstack JavaScript Delivery SDK and want to move to the TypeScript Delivery SDK without rewriting their entire website.

The migration is mostly an SDK API migration, not a language migration. You will update imports, initialization, stack calls, entry calls, asset calls, query chains, caching setup, and utility package usage. If your frontend is written in JavaScript, you can still use the TypeScript Delivery SDK from JavaScript files.

## Why this guide exists

The TypeScript Delivery SDK gives teams a modern Contentstack delivery client with stronger typing for projects that want it, a cleaner chainable API, and current package boundaries for caching and utility behavior.

That does not mean every project has to become a TypeScript project on day one. A JavaScript codebase can install and call @contentstack/delivery-sdk just like any other npm package. TypeScript support is available when you want it, but it is not a requirement for running the SDK.

Use this guide as a practical migration path:

- start by replacing the package and stack initialization


- migrate reads behind a small Contentstack wrapper


- update entries, assets, content types, and queries in predictable groups


- handle caching and utilities as separate packages when your app needs them


- verify behavior with existing pages before removing the old SDK



Useful references:

- [TypeScript Delivery SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference)


- [JavaScript Delivery SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/javascript-browser/reference)


- [Migration from JavaScript to TypeScript Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/migrate-from-javascript-to-typescript)



## How to use this guide

- If you are planning the migration, start with chapters 1 and 2.


- If you are already editing code, chapters 3 and 4 are the main translation map.


- If your app uses cache policies, Live Preview, rich text utilities, or Visual Builder helpers, read chapter 5 before you merge.


- If your team is worried that the new SDK forces a full TypeScript conversion, read chapter 6 first.


- If you want an AI coding agent to help with the migration, point it at chapter 8.






---

## Frequently asked questions

### Do I need to convert my entire project to TypeScript to use the TypeScript Delivery SDK?

No. You can install and use @contentstack/delivery-sdk from JavaScript files; TypeScript typing is optional.

### What changes are typically required when migrating to the TypeScript Delivery SDK?

Expect updates to imports, SDK initialization, stack calls, entry and asset reads, query chains, caching setup, and utility package usage.

### Is this migration primarily a language migration or an SDK API migration?

It is primarily an SDK API migration. The goal is to translate calls and patterns without rewriting the site.

### What is a practical approach to migrating without breaking existing pages?

Replace the package and stack initialization first, migrate reads behind a small wrapper, update entries/assets/queries in groups, then verify pages before removing the old SDK.

### When should I review caching, Live Preview, rich text utilities, or Visual Builder helpers during the migration?

Review these before merging if your app depends on cache policies, Live Preview, rich text utilities, or Visual Builder helpers, since they may move to separate packages or change usage.