Typescript Contentstack App SDK API Reference

The Contentstack App SDK allows you to build custom applications that interact directly with Contentstack’s content management interface. Developed in TypeScript, it provides type-safe methods to access content data, manage UI extensions, and interact with Contentstack’s core APIs. These applications run within the Contentstack interface, using the SDK to access contextual data, UI locations, and platform APIs.

This quickstart uses a Custom Field as an example to demonstrate SDK installation and initialization. You can use this initialization pattern in other UI locations as well.

Install the Contentstack App SDK in your project using npm. The SDK includes initialization methods and context objects for your app to communicate with Contentstack.

npm install @contentstack/app-sdk

Once installed, initialize the SDK to access the Custom Field context, which provides access to the current entry and field values.

import { ContentstackAppSDK } from '@contentstack/app-sdk';

const sdk = await ContentstackAppSDK.init();
const customField = sdk.location.CustomField;

if (customField) {
  const field = customField.field;
  const entry = customField.entry;
}

After initializing the SDK, you can use the available UI location APIs to build custom behavior for your app. Refer to the Overview of UI Locations section to explore supported locations and their capabilities.

The ContentstackAppSDK class provides access to all SDK properties and methods. Use it to initialize your app and interact with Contentstack’s UI locations, environment, and configuration.

location

The location property gives access to all UI locations.

const customField = sdk.location.CustomField;
const sidebar = sdk.location.SidebarWidget;

region

The region property returns the Contentstack region where the app is running.

console.log(sdk.region); // "NA", "EU", "AU"

version

The version property returns the current version of the installed app.

console.log(sdk.version); // 1

init()

The init() method initializes the SDK and returns a configured instance.

Returns: Promise<ContentstackAppSDK>

const sdk = await ContentstackAppSDK.init();

The Contentstack App SDK provides multiple UI locations that allow apps to integrate with different parts of the Contentstack interface. These locations are organized below by functional area.

Note The availability of UI locations and APIs depends on the app’s permissions, the user’s role, and the context in which the app is running. Some APIs may require management-level access or may not be available in all UI locations.

The SDK provides structured error handling for all operations to ensure reliable execution and clear reporting of failures.

Errors can be managed using standard try...catch blocks to handle issues such as initialization errors, invalid operations, or data update failures.

try {
  const sdk = await ContentstackAppSDK.init();
  const customField = sdk.location.CustomField;
  
  if (customField) {
    const field = customField.field;
    await field.setData('new value');
  }
} catch (error) {
  console.error('SDK Error:', error);
}

The following examples show how to work with fields, entries, and stack data in a plugin environment.

The following pattern allows you to respond to user actions such as field value updates or entry saves, and update the UI when entry data changes.

const entry = customField.entry;

entry.onChange((unresolved, resolved) => {
  console.log('Entry changed:', resolved);
});

entry.onSave((savedEntry) => {
  console.log('Entry saved:', savedEntry);
});

This pattern lets you read or update the current field’s value programmatically.

const field = customField.field;
const currentData = field.getData();
await field.setData('new value');

This pattern is useful for fetching related content or assets directly from your app’s context.

const stack = customField.stack;
const contentTypes = await stack.getContentTypes();
const assets = await stack.getAssets();

Note The App SDK does not provide a direct method to fetch entries by content type from the stack context.

1. Location Validation: Always check if a location exists before use.
2. TypeScript: Leverage TypeScript for a better development experience.
3. Error Handling: Implement proper error handling in production.
4. Testing: Test applications across different UI locations.
5. Design Consistency: Follow Contentstack's design guidelines.

The SDK provides comprehensive TypeScript definitions:

• ContentstackAppSDK – Main SDK class
• UILocation – UI location interfaces
• Entry – Entry object interface
• Field – Field object interface
• Stack – Stack object interface
• Store – Store object interface