Using Sanity as a Content Source

Adding Stackbit to an existing Sanity project is as simple as adding one configuration file and running one command. With a few additional steps, you can unlock inline visual editing for your site. This guide walks through the basic setup and provides resources to taking the editing experience to the next level.

Requirements#

First, note that using Stackbit with a Sanity project has a few requirements:

Node-based Framework: We currently only support site frameworks with development servers built on Node.js. See the framework guides for more info on specific frameworks. Contact us if you don't see your preferred framework or if your framework does not use Node.
Sanity Studio: Stackbit requires an instance of Sanity Studio, and currently only supports v2.

Setup#

All that it takes to make Stackbit work with Sanity is a single configuration file and a development dependency.

Dependencies#

Install the Sanity module as a development dependency.

npm install -D @stackbit/cms-sanity

Note that this is a development dependency. Stackbit is not required for your site to run in production.

Configuration#

A stackbit.config.js (or stackbit.config.ts) configuration file must exist and be properly configured for your project to work with Stackbit. Here is a simple example for a Next.js project using Node.js v16:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import { SanityContentSource } from '@stackbit/cms-sanity'

export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
  nodeVersion: '16',
  contentSources: [
    new SanityContentSource({
      rootPath: __dirname,
      studioPath: path.join(__dirname, 'studio'),
      studioUrl: '',
      projectId: process.env.SANITY_PROJECT_ID,
      token: process.env.SANITY_ACCESS_TOKEN,
      dataset: process.env.SANITY_DATASET || 'production',
    }),
  ],
}

Note the use of environment variables for connecting to your Sanity space. Be sure the variables being used here match those that are set in your local environment. You can place these values in a .env file in the root of your project when working locally. Stackbit will automatically pick these up.

See the full reference to help configure for your project.

Basic Content Editing#

When properly configured, you can immediately start editing content in your Sanity space with Stackbit.

Run Dev Server#

First, make sure your development server is running locally on your machine. (This is usually something like npm run dev.)

npm run dev

Run Studio#

Make sure your studio instance is up and running. The commands to achieve this may vary based on your configuration.

cd studio
npm start

Run Stackbit Locally#

Open another terminal session to install our CLI and run the dev command.

npm install -g @stackbit/cli
stackbit dev

Open http://localhost:8090/_stackbit in your browser to access Stackbit locally.

The first time you open Stackbit, you will be prompted to create an account and connect it to your Sanity account. Then you will be able to see the site and edit it using the content editor.

Notice that if you edit content in Stackbit, the content is also updated in Sanity, and you can preview the changes on your site!

Editing Techniques#

That's all you need to get started editing Sanity content with Stackbit! While there's much more to do, this section has a brief introduction to two additional editing techniques.

Basic Page Editing#

To unlock basic page editing, you must tell Stackbit which schemas represent pages in your dataset. This is done via the mapModels property. Using this property, you introspect the models retrieved by Stackbit to set type and urlPath on the appropriate models.

Here's an example that looks for a model called page and sets the appropriate properties.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
+
+
+
+
+
+
+
+
25

import { SanityContentSource } from '@stackbit/cms-sanity'

export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
  nodeVersion: '16',
  contentSources: [
    new SanityContentSource({
      rootPath: __dirname,
      studioPath: path.join(__dirname, 'studio'),
      studioUrl: '',
      projectId: process.env.SANITY_PROJECT_ID,
      token: process.env.SANITY_ACCESS_TOKEN,
      dataset: process.env.SANITY_DATASET || 'production',
    }),
  ],
  mapModels: ({ models }) => {
    return models.map((model) => {
      if (model.name === 'page') {
        return { ...model, type: 'page', urlPath: '/{slug}' }
      }
      return model
    })
  },
}

Once this is configured properly, you'll see an enabled page editor (pencil icon) in the left sidebar, along with a working sitemap navigator at the top of your screen. The page editor adjusts the fields contextually based on the current previewed page.

Inline Editing#

Unlocking inline editing is done by adding annotations to pages and components. This tells Stackbit exactly how to map content in the DOM to the structured data coming from Sanity schemas.

Learn more about the inline editor and refer to the technical reference for help along the way.

How this is implemented is dependent on the structure of your pages and components. But once added properly, you'll be able to highlight and edit content in-place in the preview.

Next Steps#

That's a quick introduction to adding Stackbit to a site using Sanity as a content source. But there's much more to explore. Check out our feature and concept guides for ideas on what to do next.

And you can always join the community or contact us for help along your Stackbit journey.