DatoCMS – Stackbit Docs

Stackbit supports two-way data sync between Stackbit and DatoCMS. Here is an example that uses a page content type to represent pages:

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

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.)
1
npm install -D @stackbit/types @stackbit/cms-datocms

Usage#

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

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

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.

Required: Yes

apiKey

Full-access API token, accessible from the API tokens tab (under Permissions) within a project.

Required: Yes

Storing Sensitive Values#

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

DATOCMS_API_TOKEN="..."
DATOCMS_PROJECT_ID="..."

Local Development#

DatoCMS uses webhooks to synchronize data. To work with Stackbit 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.

Restarting 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 project settings.