Using the TypeScript Delivery SDK in JavaScript projects

One of the most common migration worries is also one of the easiest to clear up: using the TypeScript Delivery SDK does not mean your whole website has to be written in TypeScript.

The package is called the TypeScript Delivery SDK because it ships strong TypeScript support and can type responses in TypeScript projects. It still runs as JavaScript in your application. A JavaScript app can import it, initialize it, and fetch Contentstack content without renaming every file to .ts.

What you'll learn

• Why the SDK works in JavaScript projects

• What you lose when you do not use TypeScript syntax

• How to migrate a JavaScript codebase safely

• How to add optional type checking with JSDoc

• How to create a path toward TypeScript later without forcing it today

A plain JavaScript example

This is valid 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,
});

export async function getHomePage() {
  return stack.contentType('page')
    .entry()
    .query()
    .equalTo('url', '/')
    .includeReference('sections')
    .find();
}

There are no interfaces, no generics, and no TypeScript compiler requirement in this file. The SDK is just an npm dependency.

What changes if you stay in JavaScript

If your files stay as .js, you should not use TypeScript-only syntax:

// TypeScript-only syntax
const entry = await stack.contentType('page')
  .entry(uid)
  .fetch<PageEntry>();

In JavaScript, call the same SDK without the generic:

const entry = await stack.contentType('page')
  .entry(uid)
  .fetch();

You still get the runtime behavior of the new SDK. You just do not get compile-time field checking unless your project adds TypeScript or JavaScript type checking later.

Use JSDoc if you want lighter type help

Some JavaScript teams want editor hints without converting the project. JSDoc can help:

/**
 * @typedef {object} PageEntry
 * @property {string} uid
 * @property {string} title
 * @property {string} url
 */

/**
 * @param {string} uid
 * @returns {Promise<PageEntry>}
 */
export async function getPage(uid) {
  return stack.contentType('page').entry(uid).fetch();
}

This is optional. It can be a useful middle step for teams that want safer content access but are not ready for a full TypeScript conversion.

A practical message for teams

The migration does not have to become a larger engineering program than intended.

You can choose one of three paths:

1. Use the TypeScript Delivery SDK from JavaScript and keep the app as JavaScript.

2. Use the SDK from JavaScript now, then add JSDoc for the most important content shapes.

3. Use the SDK from JavaScript now, then gradually move selected helper files to TypeScript later.

All three are valid. The SDK migration should improve your delivery layer without forcing unrelated decisions about framework, routing, rendering, or project language.

A good JavaScript migration boundary

For JavaScript codebases, keep SDK usage in a small set of files:

// 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 async function fetchEntry(contentTypeUid, entryUid) {
  return stack.contentType(contentTypeUid).entry(entryUid).fetch();
}

export async function fetchEntries(contentTypeUid, buildQuery) {
  const query = stack.contentType(contentTypeUid).entry().query();
  return buildQuery ? buildQuery(query).find() : query.find();
}

The rest of the app can import these helpers instead of importing the SDK everywhere. Later, if the team decides to adopt TypeScript, this file is a natural first candidate.

Key takeaways

• The TypeScript Delivery SDK can be used from JavaScript projects.

• You do not need to convert your whole codebase to TypeScript.

• JavaScript files should skip TypeScript-only syntax such as interfaces and generics.

• JSDoc can provide optional editor help in JavaScript codebases.

• A small SDK wrapper makes future TypeScript adoption easier without forcing it now.