Content Sources Interface

Stackbit's Content Source Interface (CSI) is a TypeScript interface that defines a two-way synchronization protocol between a content source and Stackbit's visual editor. A node module that implements the Content Source Interface is referred to as a content source module or content source class. An instance of a content source module is referred to as a content source instance.

While some content source modules are supported natively by Stackbit, you can use this API reference to create your own content source modules. Doing so enables your editors to edit content stored within your content sources using Stackbit's visual editor.

Overview#

The lifecycle of a content source instance can be divided into two main stages: initialization and content editing.

Initialization#

The following diagram illustrates how Stackbit loads the preview of your website, initializes the content source, and retrieves the content and content models from your content source.

Loading the website preview and initializing the content source

While this diagram assumes a cloud project, the flow is almost identical when working locally. The only difference is that you are responsible for running both the development server of your front-end web framework and Stackbit's development server.
Stackbit builds and loads the stackbit.config.ts.
The stackbit.config.ts file contains code that instantiates content source modules that implement the Content Source Interface. A Stackbit project can use different content source modules, or multiple instances of the same content source module with different constructor options.
Once instantiated, the content source instance fetch content models and content from the content sources and convert the data into a unified Stackbit format. This format is used by Stackbit to present user interface controls for editing content within the visual editor.
The stackbit.config.ts file and the content source modules are intended to be used solely by Stackbit. They are loaded and consumed exclusively by the Stackbit platform and are not directly utilized by your front-end web framework that renders the website. Therefore, the stackbit.config.ts file along with the content source modules will not have any impact on your production site.

Content Editing#

After the Stackbit app loads the preview and content of your site, you can begin editing its content. The diagram below illustrates the process of content editing.

When a content editor makes changes to the content, Stackbit sends an update operation to the relevant content source instance. The instance then converts this update into a content source-specific request, which is used to update the content source itself.
The content source instance is notified that the content has been updated and is available for consumption via its API by the content source. This notification is typically sent through server-events, polling, webhooks, or other syncing mechanisms.
After the content has been updated, the Stackbit application notifies the snippet.js within the <iframe> via a postMessage that the content was updated.
The snippet.js is responsible for triggering a content reload based on the framework of your site after it receives the notification from the Stackbit application. You can modify this behavior by using the stackbitObjectsChanged event event or by opting out of the automatic content reload altogether by enabling the customContentReload option.
Your web application reloads the preview by fetching the updated content from your content source and re-rendering the affected components.

Usage#

Adding a content source to a Stackbit project involves two steps:

Create a JavaScript class that implements the required ContentSourceInterface methods.
Create and configure an instance of your content source class and add it to the contentSources array in stackbit.config.ts.

Content Source Module#

Your content source module should implement all the required ContentSourceInterface methods to enable Stackbit to interact with your content source. The ContentSourceInterface can be imported from the Stackbit's types library @stackbit/types.

In order to properly configure your content source class, it's important to ensure that its constructor accepts all necessary configuration options. This may include project IDs, API keys, and other configuration options that are specific to your content source:

1
2
3
4
5
6
7
8
9
10
11

import type { ContentSourceInterface } from '@stackbit/types';

export class MyContentSource implements ContentSourceInterface {
  constructor(options) {
    this.projectId = options.projectId;
    this.apiKey = options.apiKey;
    // other instance properties ...
  }

  // ContentSourceInterface methods ...
}

Content Source Configuration#

To allow Stackbit to interact with your content source, create and configure an instance of your CSI class and put it into the contentSources property in stackbit.config.ts.

You can use environment variables to configure the instantiation parameters of your CSI class. When working with Stackbit cloud projects, you will define the values for your environment variables in Stackbit's project settings. When working locally, you can put these values in a .env file in the root of your project. You can also use hard-coded values for non-critical data.

1
2
3
4
5
6
7
8
9
10
11
12
13

import { defineStackbitConfig } from '@stackbit/types';
import { MyContentSource } from 'package-or-file-path';

export default defineStackbitConfig({
  // ...
  contentSources: [
    new MyContentSource({
      projectId: 'my-project-id',
      apiKey: process.env.MY_SOURCE_API_KEY,
    })
  ],
  // ...
});

Each item in the contentSources array is an object implementing the ContentSourceInterface, containing the necessary interface methods to load the content schema and perform read and write operations on the content.