Migrate from JavaScript to TypeScript

This migration guide offers a detailed breakdown of the necessary changes needed to transition from a JavaScript Delivery SDK to a TypeScript Delivery SDK. The TypeScript Delivery SDK is built upon version 4 of the JavaScript Delivery SDK.

Both SDKs have the same requirements to get started. To begin using either SDK, you will need the following:

• Contentstack account
• Node.js version 20 or later

This section illustrates the setup and installation for the JavaScript and TypeScript Delivery SDKs.

• JavaScript Implementation:

  Execute the below command to install the JavaScript Delivery SDK in your system:

  // Browser
  
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/web/contentstack.min.js"></script>
  
  
  // Node.js
  
  npm i [email protected]

• TypeScript Implementation:

  Execute the below command to install the TypeScript Delivery SDK in your system:

  // Browser
  
  <script src="https://cdn.jsdelivr.net/npm/contentstack@latest/dist/web/contentstack.min.js"></script>
  
  
  // Node.js
  
  npm i @contentstack/delivery-sdk

This section shows how to initialize the JavaScript and TypeScript Delivery SDKs. The initialization process is essentially the same for both SDKs. See the code below for an example of how to initialize the SDKs in your stack.

• JavaScript Implementation
  Execute the below command to initialize the JavaScript Delivery SDK in your system:

  import contentstack from 'contentstack';
  
  
  const Stack = contentstack.Stack({apiKey: “apiKey”, deliveryToken: “deliveryToken”, environment: “environment”});

• TypeScript Implementation
  Execute the below command to initialize the TypeScript Delivery SDK in your system:

  import contentstack from '@contentstack/delivery-sdk';
  
  
  const Stack = contentstack.stack({apiKey: “apiKey”, deliveryToken: “deliveryToken”, environment: “environment”});

A stack is a repository or a container that holds all the content/assets of your site. It allows multiple users to create, edit, approve, and publish their content within a single space.

The stack function initializes an instance of the “Stack”

Below are some methods for the Stack class that you can execute in the JavaScript SDK.

Sync

The sync method syncs your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates.

• For initializing sync

  const result = await Stack.sync({'init': true});

• For initializing sync with entries of a specific locale

  const result = await Stack.sync({'init': true, 'locale': 'en-us'
  
  });

• For initializing sync with entries published after a specific date

  const result = await Stack.sync({'init': true, 'start_date': '2018-10-22'});  

• For initializing sync with entries of a specific content type

  const result = await Stack.sync({ 'init': true, 'content_type_uid': 'session'});   

• For initializing sync with a specific type of content

  const result = await Stack.sync({ 'init': true, 'type': 'entry_published'});

• For fetching the next batch of entries using pagination token

  const result = await Stack.sync({'pagination_token': '<page_tkn>'});

• For performing subsequent sync after initial sync

  const result = await Stack.sync({'sync_token': '<sync_tkn>'});

Below are some methods for the Stack class that you can execute in the TypeScript SDK.

• setLocale

  The setLocale method sets the locale of the API server.

  stack.setLocale('en-155');

• Sync

  The sync method syncs your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates.

  • For initializing sync

    Stack.sync();  

  • For initializing sync with entries of a specific locale

    Stack.sync({ 'locale': 'en-us'});

  • For initializing sync with entries published after a specific date

    Stack.sync({ 'start_date': '2018-10-22'}); 

  • For initializing sync with entries of a specific content type

    Stack.sync({ 'content_type_uid': 'session'}); 

  • For initializing sync with a specific type of content

    Stack.sync({ 'type': 'entry_published'});
    
    //Use the type parameter to get a specific type of content. Supports 'asset_published', 'entry_published', 'asset_unpublished', 'entry_unpublished', 'asset_deleted', 'entry_deleted', 'content_type_deleted'.

  • For fetching the next batch of entries using pagination token

    Stack.sync({'pagination_token': '<page_tkn>'});

  • For performing subsequent sync after initial sync

    Stack.sync({'sync_token': '<sync_tkn>'});

An entry is the actual piece of content created using one of the defined content types. To work with a single entry, specify its UID.

Below are some methods for the Entry class that you can execute in the JavaScript SDK.

• Single Entry

  To retrieve a single entry, execute the following code and specify the content type and entry UID.

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

• includeBranch

  The includeBranch method includes the branch details in the result.

  const result = await Stack.ContentType('content_type_uid').Entry('entry_uid').includeBranch().toJSON().fetch();

• includeFallback

  The includeFallback method retrieves the entry in its fallback language.

  const result = await Stack.ContentType('content_type_uid').Entry('entry_uid').includeFallback().toJSON().fetch();

• only

  The only method selects specific field(s) of an entry.

  const result = await Stack.ContentType('content_type_uid').Entry('entry_uid').only('title').toJSON().fetch();

• except

  The except method excludes specific field(s) of an entry.

  const result = await Stack.ContentType('content_type_uid').Entry('entry_uid').except('title').toJSON().fetch();

• language

  The language method sets the language code of which you want to retrieve data.

  const result = await Stack.ContentType('content_type_uid').Entry('entry_uid').language('language_code').toJSON().fetch();

• Multiple Entries

  To retrieve details of multiple entries, execute the following code.

  const result = await Stack.ContentType('content_type_uid').Query().toJSON().find();

Below are some methods for the Entry class that you can execute in the TypeScript SDK.

• Single Entry

  To get a single entry, you need to specify the content type as well as the ID of the entry.

  interface BlogEntry extends BaseEntry {
  
  	// Entry properties
  
  }
  
  const result = await stack.contentType("content_type_uid").entry("entry_uid").fetch<BlogEntry>();

• includeBranch

  The includeBranch method includes the branch details in the result.

  const result = await stack.contentType("content_type_uid").entry().includeBranch().find<BlogEntry>();

• includeFallback

  The includeFallback method retrieves the entry in its fallback language.

  const result = await stack.contentType("content_type_uid").entry().includeFallback().find<BlogEntry>();

• only

  The only method selects specific field(s) of an entry.

  const result = await stack.contentType("content_type_uid").entry().only("field_uid").find<BlogEntry>();

• except

  The except method excludes specific field(s) of an entry.

  const result = await stack.contentType("content_type_uid").entry().except("field_uid").find<BlogEntry>();

• locale

  The locale method retrieves the entries published in that locale.

  const result = await stack.contentType('content_type_uid').entry('entry_uid').locale('locale_code').toJSON().fetch<BlogEntry>();

• Multiple Entries

  To retrieve details of multiple entries, execute the following code.

  const result = await stack.contentType("content_type_uid").entry().find<BlogEntry>();

In Contentstack, any files (images, videos, PDFs, audio files, and so on) that you upload get stored in your repository for future use. This repository of uploaded files is called assets.

The Asset method by default creates an object for all assets of a stack. To retrieve a single asset, specify its UID.

Below are some methods for the Asset class that you can execute in the JavaScript SDK.

• Single Asset

  To retrieve details of a single asset, execute the following code and specify the asset UID.

  const result = await Stack.Assets('asset_uid').toJSON().fetch();

• Multiple Assets

  To retrieve details of multiple assets, execute the following code.

  const result = await Stack.Assets().toJSON().find();

Below are some methods for the Asset class that you can execute in the TypeScript SDK.

• Single Asset

  To retrieve details of a single asset, execute the following code and specify the asset UID.

  interface BlogBG extends BaseAsset {
  
  	// Asset properties
  
  }
  
  const result = await stack.asset('asset_uid').fetch<BlogBG>();

• Multiple Assets

  To retrieve details of multiple assets, execute the following code.

  const result = await stack.asset().find<BlogBG>();

The initializer creates a Query object and provides support for all the different types of search queries.

The query class in the JavaScript Delivery SDK is not as feature-rich as the query class in the TypeScript SDK, as we have introduced some additional methods in the TypeScript Delivery SDK.

• includeReference

  The includeReference method retrieves the content of the referred entries in your response.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.includeReference("reference_field_uid").find<BlogEntry>();

• includeCount

  The includeCount method retrieves count and data of objects in the result.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.includeCount().find<BlogEntry>();
  
  
  //OR
  
  const asset = await stack.asset().includeCount().find<BlogBG>();

• orderByAscending

  The orderByAscending method sorts the results in ascending order based on the specified field UID.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.orderByAscending("field_uid").find<BlogEntry>();
  
  
  // OR
  
  const asset = await stack.asset().orderByAscending().find<BlogBG>();

• orderByDescending

  The orderByDescending method sorts the results in descending order based on the specified key.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.orderByDescending("field_uid").find<BlogEntry>();
  
  
  // OR
  
  const asset = await stack.asset().orderByDescending().find<BlogBG>();

• addParams

  The addParams method adds a query parameter to the query.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.addParams({"key": "value"}).find<BlogEntry>();
  
  
  // OR
  
  const asset = await stack.asset().addParams({"key": "value"}).find<BlogBG>();

• addQuery

  The addQuery method adds multiple query parameters to the query.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.addQuery("query_param_key", "query_param_value").find<BlogEntry>();
  
  
  //OR
  
  const asset = await stack.asset().addQuery("query_param_key", "query_param_value").find<BlogBG>();

• removeParam

  The removeParam method removes a query parameter from the query.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.removeParam("query_param_key").find<BlogEntry>();
  
  
  // OR
  
  const asset = await stack.asset().removeParam("query_param_key").find<BlogBG>();

• where

  The where method filters the results based on the specified criteria.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.where("field_UID", QueryOperationEnum.IS_LESS_THAN, ["field1", "field2"]).find<BlogEntry>();
  
  
  //OR
  
  const asset = await stack.asset().where("field_UID", QueryOperationEnum.IS_LESS_THAN, ["field1", "field2"]).find<BlogBG>();

• whereIn

  The whereIn method retrieves the entries that meet the query conditions made on referenced fields.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.whereIn("reference_uid").find<BlogEntry>();

• whereNotIn

  The whereNotIn method retrieves the entries that do not meet the query conditions made on referenced fields.

  const query = stack.contentType("content_type_uid").entry().query();
  
  
  const result = await query.whereNotIn("reference_uid").find<BlogEntry>();

• queryOperator

  The queryOperator method retrieves the entries as per the given operator.

  const query = stack.contentType("contentType1Uid").entry().query();
  
  
  const subQuery1 = stack.contentType("contentType2Uid").query().where("reference_uid1,"QueryOperation.IS_LESS_THAN, fields=90);
  
  
  const subQuery2 = stack.contentType("contentType3Uid").query().where("reference_uid2",QueryOperation.INCLUDES, fields=[20, 45]);
  
  
  query.queryOperator(QueryOperation.AND, subQuery1, subQuery2);
  
  
  const res = await query.find<BlogEntry>();

A content type is the structure or blueprint of a page or a section that your web or mobile property will display. It lets you define the overall schema of this blueprint by adding fields and setting its properties.

Below are some methods for the ContentType class that you can execute in the TypeScript SDK.

• Single Content Type

  To retrieve a specific content type, execute the following code:

  const contentType = await Stack.contentType('content_type_uid').fetch<BlogPostCT>();

• Multiple Content Type

  To retrieve multiple content types, execute the following code:

  const contentType = await Stack.contentType().find<BlogPostCT>();

• includeGlobalFieldSchema

  The includeGlobalFieldSchema method retrieves the assets published in the locale.

  const contentType = await Stack.contentType().includeGlobalFieldSchema().find<BlogPostCT>();

In a single instance, the Get Multiple Entries query will retrieve only the first 100 items of the specified content type. You can paginate and retrieve the rest of the items in batches using the skip and limit parameters in subsequent requests.

Below is the code you can execute in the JavaScript SDK for pagination:

let blogQuery = Stack.contentType('example').query(); blogQuery.skip(20).limit(20).find() 

   .then((result) => { 

       console.log(result);

    })

   .catch((error))=> { 

       console.log(error);

    });

Below is the code you can execute in the TypeScript SDK for pagination:

const query = stack.ContentType("contentTypeUid").Entry().query();

interface BlogEntry extends BaseEntry {

	note: string;

	photo: string;

	// other props 

}

const pagedResult = await query.paginate().find<BlogEntry>();


// for paginating use the next() or previous() method 

const nextPageResult = await query.next().find<BlogEntry>();

const prevPageResult = await query.previous().find<BlogEntry>();

Cache policies enable specifying the content source for the SDK retrieval. The chosen policy determines data retrieval from cache, network, or both. Apply a cache policy to a stack and/or query object as needed.

Below are some methods for the cache policies that you can execute in the JavaScript SDK.

• Setting a cache policy for a stack

  This option allows you to globalize a cache policy. This means the cache policy you set will be applied to all the query objects of the stack.

  //Setting a cache policy on a stack
  
  Stack.setCachePolicy(Contentstack.CachePolicy.NETWORK_ELSE_CACHE)

• Setting a cache policy for a query object

  This option allows you to set/override a cache policy on a specific query object.

  // setting a cache policy on a queryobject
  
  Query.setCachePolicy(Contentstack.CachePolicy.CACHE_THEN_NETWORK)

Below are some methods for the cache policies that you can execute in the TypeScript SDK.

Setting a cache policy for a stack

This option allows you to globalize a cache policy. This means the cache policy you set will be applied to all the query objects of the stack.

const stack = contentstack.Stack({ 

	apiKey: "apiKey", 

	deliveryToken: "deliveryToken", 

	environment: "environment", 

	cacheOptions = {

		policy: Policy.NETWORK_ELSE_CACHE, 

		maxAge: 3600 

	} 

});

• Our CDN services have a maximum URL size of 8KB. Any request from Typescript Delivery SDK that exceeds this limit will get a 400 error.
• The Typescript Delivery SDK does not support multiple content types referencing in a single query.
• The Typescript Delivery SDK currently does not support querying Global Field schemas. However, you can include these details when querying content type details by using the include_global_field_schema query parameter.