Visual editing /Visual Editor /Content sources /

Content sources overview

Connect content sources to Visual Editor using the Content Source Interface (CSI).

Content Source Interface (CSI) provides a two-way synching mechanism between the visual editor and your content source(s) (API-based CMS, remote database, files, etc.).

CSI defines methods to load the content and its schema from the underlying content source, perform CRUD operations (create/read/update/delete) on the content, upload assets, and other content-related operations.

Some modules are developed & supported by Visual Editor, but you can build your own content sources as well.

# Example usage

Enabling this feature for any content source requires instantiating a module within the contentSources config property. Here's an example using Contentful.

// stackbit.config.js
import { ContentfulContentSource } from "@stackbit/cms-contentful";

export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN
    })
  ]
  // ...
};

If configured properly, you will immediately be able to see your models in the content panel.

List of content models.

You can then drill into any object and see two-way sync in action. Edit it in Visual Editor, and the source gets updated. Edit it in the source, and within moments Visual Editor will show the updated value.

Page editing in content panel.

# CSI and your code

CSI modules and the stackbit.config.js file are not loaded by your site's code. Rather, these are used by Visual Editor’s dev server to load and modify data through Visual Editor.

Your own code for fetching data from any of its content sources is not impacted or replaced by the CSI, at all. This means that:

You are still responsible for writing the code that retrieves content from your source(s) and feeds them into your pages and components.
You don't have to make changes to your site to be able to use CSI (assuming that your content is not hard-coded into your code)
Any dependencies needed for CSI can be installed as development dependencies, and are not needed for your live site.

# Supported sources

The following modules are supported directly by Visual Editor:

# Experimental sources

We're currently experimenting with these additional sources:

Strapi
Shopify
Figma

For inquiries and requests regarding new sources, please contact us.

# Use a content source

Working with a supported content source takes just a few steps. Assuming you already have the source itself (e.g. the CMS) ready to go, the process usually looks like this:

Install the NPM package for the module (as a development dependency).
Add the content source to the contentSources array in your configuration file.

Here's an example that adds Contentful as a content source.

// stackbit.config.js
import { ContentfulContentSource } from "@stackbit/cms-contentful";

export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN
    })
  ]
  // ...
};

# Add multiple sources

Because contentSources is an array of instantiated classes, adding another source is a matter of adding a new item to the array.

This means that using two accounts from the same service provider is also possible. Here's an example:

// stackbit.config.js
import { ContentfulContentSource } from "@stackbit/cms-contentful";

export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID_01,
      environment: process.env.CONTENTFUL_ENVIRONMENT_01,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN_01,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN_01
    }),
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID_02,
      environment: process.env.CONTENTFUL_ENVIRONMENT_02,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN_02,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN_02
    })
  ]
  // ...
};

# Authenticate content editor accounts

To be able to make changes to content in the source requires connecting a Visual Editor user account to an account to the content source. Here’s the process for making these connections:

From the visual editor dashboard, in the top right, select your avatar. Next, select Linked accounts.
Next to the content source you want, choose Connect.
Follow the prompts to connect with your content source.

# Supported connections

The following third-party connections are available:

Contentful
DatoCMS
GitHub
Sanity

# Bring your own source

Because content source modules are defined as instantiated JavaScript classes in the configuration file, you can bring your own content source, even if not officially supported by Visual Editor.

Use the CSI API reference to ensure you're implementing the JavaScript class properly.

# Module requirements

Any content source that can read and write data via an API or direct local access can be used as a content module. This includes:

Headless (or API-based) CMS (e.g. Contentful)
Database as a Service (e.g. PlanetScale)
Internal product database (e.g. PostgreSQL)
Non-traditional services (e.g. Figma)
File-based content (e.g. Markdown files)

# Using TypeScript

We recommend using TypeScript in your CSI module. This benefits both you by ensuring that you implement all necessary methods. It also benefits developers that using the module by making it easier to discover required options when instantiating the class in their configuration file.

# Migrate to a new source

CSI makes it trivial to migrate to a new content source without sacrificing content downtime or adding complexity to your code.

You can move one page at a time from the old source to the new source as long as:

You have properly configured the content sources, and ...
Your front-end code supports the content structure from both sources.

# Configuration example

Ensure that you're adding both sources to your config file:

// stackbit.config.js
import { MyOldSource } from "my-old-source";
import { MyNewSource } from "my-new-source";

export default {
  contentSources: [
    new MyOldSource({
      // configuration options ...
    }),
    new MyNewSource({
      // configuration options ...
    })
  ]
  // ...
};

Then you can add a new page to the new source and delete the old page from the old source. Do this one at a time until you've moved all the content to the new content source.

Last updated: November 5, 2024

Did you find this doc useful?

Your feedback helps us improve our docs.