Configuration

Primary Stackbit configuration file reference (stackbit.config.js) that enables you to customize the visual editing experience for your site.

Current Version: 0.6.0

Some options may not be available if using an earlier version of Stackbit, 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 with Stackbit 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 Stackbit 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 Stackbit configuration file to run in Stackbit, whether locally or in our web application. However, you can still run your project in Stackbit with a minimal amount of configuration. See below.

  • 1
  • 2
  • 3
  • 4
export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
}

This is enough to get your project running with Stackbit. However, Stackbit 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.

TypeScript Example

Here is the example above written in TypeScript:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
import { ContentfulContentSource } from '@stackbit/cms-contentful'
import type * as Stackbit from '@stackbit/sdk'

const stackbitConfig: Stackbit.RawConfig = {
  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}' },
  },
}

export default stackbitConfig

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 Stackbit configuration and visual editing capabilities your project is using.

Required
Yes
Allowed Values
A valid version number in semver syntax. Current version: 0.6.0
  • 1
  • 2
  • 3
  • 4
export default {
  stackbitVersion: '~0.6.0',
  // other properties ...
}
  • Versions prior to 0.4.0 are deprecated.

Configuration Topics

The following sections cover configuration references for specific features and concepts.