Using Contentful as a Content Source

Adding Stackbit to an existing Contentful 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 each step in the process.

Requirements#

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

1. 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.
2. Draft Content: Stackbit runs your development and enables you to see changes before deploying to production. This means that your site must display draft content from the CMS when running the dev server.

Setup#

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

Dependencies#

Install the Contentful module as a development dependency.

npm install -D @stackbit/cms-contentful

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:

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

See the full reference to help configure for your project.

Basic Content Editing#

When properly configured, you can immediately start editing content in your Contentful 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 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 Contentful account. Then you will be able to see the site and edit it using the content editor.

This covers the bare minimum requirements to get Stackbit to work for your Contentful project. Notice that if you edit content in Stackbit, the content is also updated in Contentful, and you can preview the changes on your site!

Continue to see how you can take editing to the next level with additional configuration.

Page Editing#

Notice that the page editor and sitemap navigator are disabled and empty.

This is because you haven't told Stackbit which content types represent pages for your site. You can do this in the config file. Here's an example for a site with a page model:

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

Refer to the modeling technical reference for defining models.

Once you've added the proper models, you'll be able to see a list of your pages in the sitemap navigator.

And you'll be able to expand the page editor to edit fields directly, in-context, with a real-time preview.

Advanced Editing#

You can take your editing experience to the next level using a few other features. Each of these tasks is very specific to your code base. The sections below are meant only to get you started.

Additionally, following the Contentful getting started tutorial will help you practice the basics.

Inline Editing#

Annotations are how Stackbit knows how to highlight elements on the page and where to retrieve/store content for those elements. Annotations create a mapping between your content source and the content displayed by your site.

The annotations API reference will help you annotate objects.

Content Presets#

Presets are a great way to help content editors move fast by creating predetermined starting points for content. Here's the reference.

There are a few nuances in working with presets for Contentful projects. See this doc for more information.

Multiple Content Sources#

Stackbit can accommodate editing content from multiple sources, including multiple Contentful spaces. Simply add another class instantiation to the contentSources array in the configuration file.

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,
    }),
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID_ALT,
      environment: process.env.CONTENTFUL_ENVIRONMENT_ALT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN_ALT,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN_ALT,
    }),
  ],
  models: {
    page: { type: 'page', urlPath: '/{slug}' },
  },
}

Create Stackbit Cloud Project#

When you're ready to collaborate on your project, make sure your changes are pushed to GitHub, and then create a new cloud project.