Use DatoCMS with Visual Editor

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

Example configuration

Here is an example that uses a page content type to represent pages:

// stackbit.config.ts
import { defineStackbitConfig } from '@stackbit/types'
import { DatoCMSContentSource } from '@stackbit/cms-datocms'

export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  contentSources: [
    new DatoCMSContentSource({
      apiToken: process.env.DATOCMS_API_TOKEN!,
      projectId: process.env.DATOCMS_PROJECT_ID!,
    }),
  ],
  modelExtensions: [{ name: 'page', type: 'page', urlPath: '/{slug_field}' }],
})

Prerequisites

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

• A DatoCMS project with models and content.

• A full-access API token and ID of the project, both stored as environment variables. (See options below.)

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

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

Usage

import { DatoCMSContentSource } from '@stackbit/cms-datocms'

new DatoCMSContentSource({
  apiToken: '...',
  projectId: '...',
})

Options

The following are all required options:

• projectId: identifying value of the DatoCMS project. It can be found when viewing the project from the dashboard. It is not the name of the project.
• apiKey: full-access API token, accessible from the API tokens tab (under Permissions) within a project.

Store sensitive values

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

# .env
DATOCMS_API_TOKEN="..."
DATOCMS_PROJECT_ID="..."

Local development

DatoCMS uses webhooks to synchronize data. To work with Visual Editor in local development, the easiest method is to use an ngrok tunnel and pass the tunnel URL when running stackbit dev.

Install ngrok

After signing up for an ngrok account, install the agent on your machine.

Start ngrok agent

With your development server running in another terminal window, start the ngrok agent on port 8090.

ngrok http 8090

This will output a publicly-accesible URL from which you can access localhost:8090.

Session Status    online
...
Forwarding        http://xyz.ngrok.app -> http://localhost:8090
Forwarding        https://xyz.ngrok.app -> http://localhost:8090

Start stackbit dev

When starting stackbit dev, use the ngrok URL as part of the csi-webhook-url option, being sure to maintain the path /_stackbit/onWebhook.

stackbit dev --csi-webhook-url https://xyz.ngrok.app/_stackbit/onWebhook

Now you are good to open localhost:8090/_stackbit and start developing locally.

Restart ngrok

When restarting the ngrok agent, you will typically receive a different URL.

This will result in an error saying that a webhook with a name stackbit-webhook-local already exists. If this happens, delete the stackbit-webhook-local webhook in your DatoCMS settings.