Install and initialize the TypeScript Delivery SDK

The safest migration starts with a clean SDK boundary. Replace the package, create the new stack client in one place, and keep the rest of your app calling that wrapper until each fetch path is migrated.

What you'll learn

• How to replace the JavaScript Delivery SDK package

• How to initialize the TypeScript Delivery SDK

• How to keep environment variables stable during the migration

• How to create a wrapper that works from JavaScript or TypeScript

• How to verify the first request before converting the rest of the app

Replace the package

Remove the old JavaScript SDK when you are ready to switch:

npm uninstall contentstack
npm install @contentstack/delivery-sdk@latest

If you need to migrate gradually, you can keep both packages temporarily, but avoid using both in the same helper file. Name the old and new clients clearly so reviewers can see which paths have moved.

Initialize the new stack client

The JavaScript SDK initialization usually looks like this:

import contentstack from 'contentstack';

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

The TypeScript Delivery SDK uses the new package and lowercase stack() initializer:

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

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

Keep your existing environment variable names if they already work for your app. The SDK does not require you to rename CONTENTSTACK_API_KEY, CONTENTSTACK_DELIVERY_TOKEN, or CONTENTSTACK_ENVIRONMENT.

Use one wrapper module

A wrapper gives the migration a stable place to happen:

// lib/contentstack.js
import contentstack from '@contentstack/delivery-sdk';

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

export function contentType(uid) {
  return stack.contentType(uid);
}

Now the rest of the app can move from direct SDK calls to helper functions:

import { contentType } from './lib/contentstack';

export async function getBlogPost(uid) {
  return contentType('blog').entry(uid).fetch();
}

This is useful even in TypeScript projects because it keeps credentials, region configuration, plugins, cache policy, and preview settings in one place.

Add response types when you want them

In a TypeScript file, you can add response types gradually:

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

interface BlogPost extends BaseEntry {
  title: string;
  url: string;
}

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

export async function getBlogPost(uid: string) {
  return stack.contentType('blog').entry(uid).fetch<BlogPost>();
}

You do not need to add all response types before shipping the migration. Start with high-value content types where typed fields prevent real mistakes.

Verify one request

Before converting every query, verify a single published entry:

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

console.log(entry.uid, entry.title);

If this fails, check credentials and environment first. If the old SDK worked and the new SDK does not, make sure the new stack client uses the same region, environment, delivery token, and branch assumptions as the old client.

Key takeaways

• Install @contentstack/delivery-sdk to use the TypeScript Delivery SDK.

• Use contentstack.stack() instead of contentstack.Stack().

• Keep SDK setup in one wrapper so the migration stays controlled.

• You can add TypeScript response types incrementally.

• Verify one entry fetch before migrating every page.