Skip to main content

Install the Delivery SDK

Install the Delivery SDK to give your app a stack that reads your content from Contentstack. It's the first of the three SDKs you install, because Studio reads every template, section and entry through this stack.

The example on this page is the Blog stack, in North America, read by a Next.js App Router app. You'll create the stack in lib/contentstack.ts and read the local environment.

Prerequisites​

  • Your stack's API key, a delivery token and the name of an environment, such as local. See What you need in your stack.
  • The region your stack is in. A stack outside North America needs its own host.
  • The environment variable prefix your framework uses. The example uses NEXT_PUBLIC_ for Next.js. Vite uses VITE_, read through import.meta.env. Create React App uses REACT_APP_, Astro uses PUBLIC_, and Remix uses no prefix.

What the Delivery SDK does for Studio​

The Delivery SDK, @contentstack/delivery-sdk, reads published content from Contentstack's delivery API. Studio doesn't fetch content itself. It reads every template, section and entry through the stack you give it. So the stack's region and host decide which Contentstack data center Studio reads from.

Installing the Studio SDK doesn't install the Delivery SDK, so you install it yourself. The Studio SDK is built against Delivery SDK 4.5 and later 4.x versions.

Faster ways to do this​

  • Skill. Ask your agent to install Studio, and it uses install-studio. It installs the Delivery SDK, Live Preview and the Studio SDK together, so it does this page and the next two in one pass. It checks your API key and delivery token against the delivery API before it writes any code. It adds no routes. See What are skills?

No skill installs the Delivery SDK on its own, and no CLI command installs the SDKs.

Install the Delivery SDK​

Install it from public npm. You don't need registry settings or an access token.

npm install @contentstack/delivery-sdk

With Yarn or pnpm, run yarn add or pnpm add with the same package name.

Create the Delivery SDK stack​

Create the stack in one module and export it, so Live Preview and the Studio SDK use the same stack. In the example, that module is lib/contentstack.ts.

  1. Add the values to your environment file, with your framework's prefix:

    NEXT_PUBLIC_CONTENTSTACK_API_KEY=your_stack_api_key
    NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token
    NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=local

    Read the delivery token from an environment variable, and never commit it.

  2. Create lib/contentstack.ts. Import the default export and call contentstack.stack with the three values:

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

    export const stack = contentstack.stack({
      apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
      // Read the token from the environment. Never commit it.
      deliveryToken: process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN!,
      environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT!,
    });

  3. If your stack is outside North America, also set region and set host to your region's delivery host. Contentstack's regions docs list the host for each region. The defaults you get when you leave both out only work for North America stacks, like the Blog stack. You can read the region from NEXT_PUBLIC_CONTENTSTACK_REGION.

Your site never needs a management token for Studio. The stack is all Studio takes.

Check the Delivery SDK values are set​

Log the values lib/contentstack.ts reads, once, and check that none of them is undefined. Remove the log when you're done.

console.log(
  process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY,
  process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT,
);

The check that Studio reads your content through the stack comes at the end of setup, in Verify your setup end to end.

Next, add Live Preview to the same stack: Install Live Preview.

If it doesn't work​

A value is undefined at runtime​

The variable has the wrong prefix for your framework, or the dev server started before you added it. Your framework reads env files when the dev server starts, so restart it after every change.

A .env.local file overrides .env, so a stale .env.local can hold old values. Check it too.

A value reads as the text undefined​

If an env file holds the literal text undefined, the SDK sends it as is and the delivery API rejects it. Put the real value in the file, or remove the line.

Studio reports STACK_NOT_FOUND_ON_HOST​

The API key is wrong, or the host is for a different region from your stack. The message starts like this:

[Contentstack Studio] STACK_NOT_FOUND_ON_HOST: Contentstack did not find a stack for this API key on cdn.contentstack.io.

Copy the API key again from your stack, update the environment file and restart the dev server. If the key is right, set region and host to your stack's region.

Studio reports ENVIRONMENT_NOT_FOUND​

The environment name is wrong, or the delivery token doesn't cover that environment. The message names the environment your stack sent. Compare it with the environments in Contentstack, and check the delivery token's environments.

Studio reports UPSTREAM_ERROR or TRANSPORT_FAILED​

A wrong delivery token has no code of its own. It shows as UPSTREAM_ERROR or TRANSPORT_FAILED.

Copy the delivery token again from your stack, update the environment file and restart the dev server. Every code is in the Error message index.

Report a problem with this page