Set Up Studio for a CSR Project

Note: Studio is currently part of an Early Access Program and may not be available to all users. Contact the Contentstack support team; they will coordinate with the appropriate stakeholders to review eligibility.

Studio lets you visually design, configure, and render web experiences by combining prebuilt or custom components, CMS-managed content, and design system tokens, without hand-writing HTML or CSS for each page.

This setup guide walks you through integrating Studio into a React project, from installing SDKs to rendering your first composition. By the end of this guide, you’ll have a working configuration that:

• Connects your front-end to your Contentstack stack
• Loads composition data (spec) from Studio
• Renders the composition dynamically
• Supports Live Preview and Visual Builder for in-context editing

Before you begin, ensure you have:

• A stack with Live Preview enabled
• An existing Studio project linked to your stack

Studio requires two SDKs:

1. Studio React SDK

   This SDK provides the tools to fetch and render compositions from Studio.

   Run one of the following commands in your project directory:

   npm i @contentstack/studio-react

   Or

   yarn add @contentstack/studio-react

2. Contentstack Delivery SDK

   Studio uses this SDK internally to fetch your content from the CMS.

   npm i @contentstack/delivery-sdk

   Or

   yarn add @contentstack/delivery-sdk

These tokens authenticate your front end to fetch published and preview content from Contentstack.

To create a Delivery and Preview token, log in to your Contentstack account and perform the following steps:

1. Go to your stack, navigate to the settings panel, and select Tokens.
2. Click Delivery Token to create a new token.

   Tip: If you are on the Management Tokens tab, you can press “Alt + O” (Windows) or “Option + O” (Mac) to navigate to the Delivery Tokens tab.

3. Enter a Name (required) and a Description (optional) for the Delivery Token.
4. In the Scope section, choose the Branches or Aliases to associate with this token.
5. Select the Publishing Environments for which to generate the Delivery Token.
6. Enable the Create Preview Token toggle to generate a Preview Token.
7. Click Generate Token.

A new token appears in both the Delivery Token and Preview Token fields. You can copy the tokens for later use in your SDK configuration.

Create a configuration file (e.g., src/studio/index.ts) to store your Studio setup.

// src/studio/index.ts
import contentstack from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: "api_key",
  deliveryToken: "delivery_token",
  environment: "environment",
  live_preview: {
    preview_token: "preview_token",
    enable: true,
  },
});

In your main file (e.g., src/index.ts), import the Studio config:

import { studioSdk } from "@contentstack/studio-react";

studioSdk.init({
  stackSdk: stack,
});

This ensures the SDKs are initialized before your app renders any compositions.

To activate the configuration, import the index.ts in your application’s main file:

// src/index.ts
import "./studio";

This ensures the SDKs are initialized before your app renders any composition.

The Studio Spec contains:

• The structure of your page (components, layers)
• Metadata (tokens, settings)
• Bound content from the CMS

In your main component (App.tsx), use the useFetchSpecOptions hook to retrieve it.

// src/App.tsx
import { useCompositionData } from "@contentstack/studio-react";

export function Home() {
  const { specOptions, isLoading, error } = useCompositionData({
    compositionUid: "page", // Replace with your composition UID
  });
}

Once you have the spec, pass it to StudioComponent to render the layout.

// src/App.tsx
import {
  useFetchSpecOptions,
  StudioComponent,
} from "@contentstack/studio-react";

export function Home() {
  const { specOptions, isLoading, error } = useFetchSpecOptions({
    compositionUid: "page",
  });

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <div>Failed to fetch compositions</div>;
  }

  return <StudioComponent specoptions="{specOptions}">;
}

This renders the layout and content exactly as defined in Studio.

If you are using React Router or similar, you can fetch compositions dynamically based on the URL rather than hardcoding UIDs:

• Use the current path to derive the compositionUid
• Use a single renderer component to load any page
• New compositions will automatically render without code changes

After completing the configuration steps, confirm that Studio is working as expected in your local environment.

1. Run your project

   Start your local development server to load your React or Next.js application.

   npm start

   Or

   yarn start

   This will compile your application and launch it on http://localhost:3000.

2. Open the application in a browser

   Navigate to your local URL (e.g., http://localhost:3000) and look for the composition.

   1. If everything is set up correctly, you should see the layout and components as defined in Studio.
   2. If you see a blank page, check the console for JavaScript errors and ensure the compositionUid matches the UID from Studio.
3. Test Live Preview (if enabled)

   If your stack has Live Preview enabled:

   1. Open the same composition in Visual Builder within Contentstack.
   2. Edit a piece of content (e.g., a heading or image).
   3. Save the entry.
   4. Switch back to your local app – the change should appear instantly without refreshing.
   5. This confirms:
      • Your preview token is working
      • Live Preview is properly connected
      • Data binding between CMS and components is working

      Tip: If changes don’t appear, verify your token settings and ensure the enable property is set to true in the live_preview configuration.

You’ve now connected your front-end application to Studio. With your setup complete, you can:

• Build custom components
• Bind them to live content
• Use design tokens from your design system
• Reuse layouts across pages

As your project grows, Studio helps maintain consistency, accelerate iteration, and keep content creators and developers in sync.