Content Sources Interface

Netlify Visual Editor's Content Source Interface (CSI) is a TypeScript interface that defines a two-way synchronization protocol between a content source and the 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 the visual editor, 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 the 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 the visual editor loads the preview of your website, initializes the content source, and retrieves the content and content models from your 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 the visual editor's development server.
• The visual editor 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 visual editor 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 visual editing format. This format is used by the visual editor 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 the visual editor. They are loaded and consumed exclusively by the visual editor 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 visual editing 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, the visual editor 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 visual editing 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 visual editing 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 visual editor 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 the visual editor to interact with your content source. The ContentSourceInterface can be imported from the visual editor'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:

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 the visual editor 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 visual editing cloud projects, you will define the values for your environment variables in the visual editor'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.

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.