Configuration

Some options may not be available if using an earlier version of the visual editor, as specified in the stackbitVersion property.

stackbit.config.js (or stackbit.config.ts) is a configuration file placed in the root of your project that enables you to customize the visual editing experience for your project. Note that this file is not required for your project to run in production.

Examples#

Here are a few examples of common configuration patterns in the visual editor sites.

Typical Configuration#

Here is a simple example that uses a supported framework (Next.js) and a remote content source (Contentful):

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

import { ContentfulContentSource } from '@stackbit/cms-contentful'

export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
  nodeVersion: '16',
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN,
    }),
  ],
  models: {
    page: { type: 'page', urlPath: '/{slug}' },
  },
}

In this example, there is a content type (model) in Contentful with an ID of page that serves as the primary page model for the site, using a field called slug to build the URL path for each page.

Minimal Configuration#

Your site must have a visual editing configuration file to run in the visual editor, whether locally or in our web application. However, you can still run your project in the visual editor with a minimal amount of configuration. See below.

export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
}

This is enough to get your project running with the visual editor. However, the visual editor will not know where your content lives. After you're up and running, you'll want to configure your content source.

Using TypeScript#

To use TypeScript to add type checking and autocompletion to your configuration, rename stackbit.config.js to stackbit.config.ts.

The visual editor types are exported from @stackbit/types and can be used by exporting the defineStackbitConfig function from your configuration file. See below for an example.

TypeScript Example#

Here is the typical configuration example from above, written in TypeScript:

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

import { ContentfulContentSource } from '@stackbit/cms-contentful';
import { defineStackbitConfig } from '@stackbit/types';

export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
  nodeVersion: '16',
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN,
    }),
  ],
  models: {
    page: { type: 'page', urlPath: '/{slug}' },
  },
}

Useful Types#

The following types are likely to be most useful when configuring your project:

RawConfig: The main configuration object.
YamlDataModel: For a model in the models property using type data.
YamlObjectModel: For a model in the models property using type object.
YamlPageModel: For a model in the models property using type page.

Configuration Properties#

Below you will find the base configuration properties, as well as links to sections with more detailed configuration references.

`stackbitVersion`#

The version of the visual editing configuration.

Required

Yes

Allowed Values

A valid version number in semver syntax. Current version: 0.7.0

export default {
  stackbitVersion: '~0.6.0',
  // other properties ...
}

Versions prior to 0.4.0 are deprecated.

`useESM`#

Indicates whether or not stackbit.config.ts should be compiled using ESM. This is helpful when one of your stackbit.config.ts dependencies is an ES module. The default is to use CJS.

This flag is available with @stackbit/sdk version 1.0.13 or later, and @stackbit/types version 0.11.2 or later.

Required

Allowed Values

true, false

Default

false

export default {
  useESM: true,
  // other properties ...
}

List of Properties#

All other properties are currently separated into individual topic pages with additional details.