Contentful Configuration

Stackbit has a tight integration to support Contentful as one or more of your content sources. This guide covers what you need to know about configuring Stackbit to provide a two-way data sync between your Contentful space(s).

Here is an example configuration that uses Next.js as the site framework and uses a page content type to represent pages:

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

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}' },
  },
})

Notice the following:

• ContentfulContentSource is being loaded from the @stackbit/cms-contentful which must be installed first. This package is not needed in your production site.
• Contentful is being configured using local environment variables. Stackbit will automatically load a .env file in the root of your project.
• There is a content type with an ID of page that is being used to store page data in Contentful. That content type has a field with name slug that determines the URL path at which the page is made available.

Prerequisites#

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

• A Contentful space with content.
• The proper API keys that can access your content. (See options below.)

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

  • 1

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

Usage#

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

new ContentfulContentSource({
  spaceId: '...',
  environment: '...',
  previewToken: '...',
  accessToken: '...',
})

Options#

Storing Sensitive Values#

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

CONTENTFUL_SPACE_ID="..."
CONTENTFUL_ENVIRONMENT="..."
CONTENTFUL_PREVIEW_TOKEN="..."
CONTENTFUL_MANAGEMENT_TOKEN="..."

Content Type Inference#

The Contentful CSI module infers all Contentful content types to be Stackbit data models, unless otherwise specified.

Therefore, page models must be defined using the modelExtensions property.

Using Multiple Spaces or Environments#

The contentSources property is an array of content sources that are all pulled together with Stackbit. You can add another by instantiating another class as another item in the array, while using separate environment variables for the options.

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

export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID_01,
      environment: process.env.CONTENTFUL_ENVIRONMENT_01,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN_01,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN_01,
    }),
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID_02,
      environment: process.env.CONTENTFUL_ENVIRONMENT_02,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN_02,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN_02,
    }),
  ],
  // ...
}

Conflicting Model Names#

Note that if there are conflicting model names (IDs), the model that was loaded last (later in the contentSources array) will override those defined earlier.