Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /Content sources /

Use Contentstack with Visual Editor

Visual Editor supports two-way data sync between Visual Editor and Contentstack.

# Example configuration

Here is an example that configures the content source and creates a custom sitemap to override the default sitemap behavior.

// stackbit.config.ts
import process from "process";
import path from "path";
import {
  defineStackbitConfig,
  DocumentStringLikeFieldNonLocalized,
  SiteMapEntry
} from "@stackbit/types";
import { ContentstackContentSource } from "@stackbit/cms-contentstack";

require("dotenv").config({ path: path.resolve(process.cwd(), ".env") });

export default defineStackbitConfig({
  stackbitVersion: "~0.5.0",
  ssgName: "nextjs",
  nodeVersion: "18",
  styleObjectModelName: "siteConfig",
  contentSources: [
    new ContentstackContentSource({
      apiKey: process.env.CONTENTSTACK_API_KEY!,
      managementToken: process.env.CONTENTSTACK_MANAGEMENT_TOKEN!,
      authtoken: process.env.CONTENTSTACK_AUTHTOKEN,
      branch: process.env.CONTENTSTACK_BRANCH!,
      publishEnvironmentName: "production",
      skipFetchOnStartIfCache: true
    })
  ],
  sitemap: ({ documents }) => {
    return documents.reduce((sitemap: SiteMapEntry[], document) => {
      if ("url" in document.fields) {
        const titleValue = (document.fields.title as
          | DocumentStringLikeFieldNonLocalized
          | undefined)?.value;
        const urlValue = (document.fields
          .url as DocumentStringLikeFieldNonLocalized).value;
        sitemap.push({
          label: titleValue,
          urlPath: urlValue,
          document: document
        });
      }
      return sitemap;
    }, []);
  }
});

# Prerequisites

To be able to work with Contentstack, you must first have the following:

  • A Contentstack project with models and content.

  • The API key for your stack, your stack’s management token, and an authentication token — all stored as environment variables. Refer to options below to learn more.

  • Installed @stackbit/cms-contentstack package as a development dependency. We also recommend @stackbit/types to help with configuration.

    npm install -D @stackbit/types @stackbit/cms-contentstack

# Usage

import { ContentstackContentSource } from "@stackbit/cms-contentstack";

new ContentstackContentSource({
  apiKey: "...",
  managementToken: "...",
  authtoken: "...",
  branch: "...",
  publishEnvironmentName: "...",
  skipFetchOnStartIfCache: "..."
});

# Options

The following are all required options unless otherwise noted:

  • apiKey: the API key for your stack.

  • managementToken: the management token for your stack. Ensure you use a token with the following configuration:

    • The Scope includes the branches you want to use with this project
    • The Permissions include both Read and Write
    • The Expiry is set to Never.

  • authtoken: an Authtoken that you can generate by executing the log in to your account request to the Contentstack API.

  • branch: the stack branch you want to use in your Visual Editor project.

  • publishEnvironmentName: (optional) the stack environment to publish.

  • skipFetchOnStartIfCache: (optional) when set to true, the visual editor will check for and use cached documents and assets when content sourcing starts, instead of fetching from the source. Newer versions of the documents and assets will be fetched by polling content. The default is false.

    When you use stackbit dev locally, the skipFetchOnStartIfCache flag will only apply when you run the command without webhooks. For example, when --csi-webhook-url is not provided.

# Store sensitive values

Sensitive values can be stored in a .env file in the root of your repository, which will then be available when the Visual Editor configuration file is loaded.

# .env
CONTENTSTACK_API_KEY="..."
CONTENTSTACK_MANAGEMENT_TOKEN="..."
CONTENTSTACK_AUTHTOKEN="..."
CONTENTSTACK_BRANCH="..."

# Limitations