Add Stackbit to Existing Site

How to add Stackbit to an existing website.

Adding Stackbit to an existing project is as simple as adding one configuration file and running one command. With a few additional steps, you can then unlock inline visual editing and other power features for your site.

This guide assumes using Contentful and Next.js, but the needed steps are very similar for most content sources and frameworks. See our integration guides for detailed information.

First, let's get you running with Stackbit on your local development machine.

Start Locally

1. Run Your Development Server

For content changes to appear in the browser immediately after they're made, ensure that you're:

  • Running your web server in development mode (for Next.js projects, this typically means running npm run dev or next dev).
  • Fetching draft content from the content source rather than only published content.

For Contentful, this means replacing the delivery token with a preview token when initializing the Contentful classic JS client or calling their GraphQL-based REST API. There's no more need for fragile solutions for enabling previews in production.

2. Add Configuration File

A configuration file must exist at the root of your project. Here's an example configuration for a project using Next.js with Contentful:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
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.

3. Run Stackbit in Local Development Mode

Install our command-line tool:

  • 1
npm install -g @stackbit/cli

The next command to run is stackbit dev, which acts as a middleman connecting our visual editor to connect to your local web server.

  • 1
stackbit dev

If your local web server does not use port 3000, append --port <number>.

Upon starting, the stackbit dev process will output a unique URL:

  • 1
  • 2
  • 3
  • 4
> stackbit dev
info: Site directory: /path/to/project/...
info: Server started. Forwarding requests to: localhost:3000
info: ⚡ Open https://app.stackbit.com/local/eyJpIoiUYjFkMUz4NzEyNGJkYjQ4YjBiNUiLCo4MkwJ2IjoiMC4xLjiLCOiJnaXQifQ== in your browser

Open this URL and you will get the visual editor connected to your local web server. The first time you do this, you will be prompted to create an account.

Assuming the credentials you've passed are correct, you are now able to click the Content Tab on the left sidebar and see all content in the CMS. Good! but to be useful, there's one more step.

4. Define How Pages Map to URLs

To enable the sitemap navigator and page editor, you need to tell Stackbit which content models represent pages in your project, by appending to your config file.

Here's a simple yet common example, which assumes that the content model representing pages in the CMS is named page, and it has a slug field which directly maps to a URL:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • +
  • +
  • +
  • 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}' },
  },
}

When you save this file, the visual editor should immediately pick up the changes and enable the sitemap and page-level editing.

Next Up

Annotate Components

Annotations are simple HTML data attributes which mark for the visual editor which element on the page represent what content object, or a specific field in it. Here's an example:

  • 1
  • 2
  • 3
<div data-sb-object-id="object id in the content source">
  <h2 data-sb-field-path="title">{ title }</h2>
</div>

Annotations make an editor's work faster and easier, as they can click on an element to start editing it, no matter how deeply nested the underlying content is. They also unlock powerful features, namely component presets and component styles.

No anotation is mandatory, and we recommend that you enable page-level editing first, then gradually add annotations to benefit content editors. Head over to the API reference to understand the full capabilities of annotations.

Create a Cloud-based Project

To let content editors work on the site, connect your repository to a new cloud-based Stackbit project, in which we run your website's development server (see how this works and requirements).

Additional Content Sources

We can support any API-based content source, plus editing from multiple content sources within the same project. Contact us to learn more.

Need Help?

If you want to get a quick hands-on introduction to Stackbit first, take the tutorial, then apply what you've learned. For more supprt options, see here.