Integrate Stackbit with an Existing Site

This guide will take you through a quick example of integrating Stackbit's visual editing capabilities into your existing site.

What we're going to do is load a JSON object into a page and render the object's title property on the page. We'll then install Stackbit and enable visual editing on that title.

Following this guide, you will find answers to common problems and a series of suggested next steps for applying this process at scale.

If you get stuck along the way, join our community to ask for help.

Requirements

Integrating Stackbit into an existing site requires a Next.js site run with Node v14 or above.

If you've met the requirements, you're ready to get started. Let's go!

Add Page Title from JSON File

Open your Next.js project and start your development server (usually npm run dev).

Add JSON Data File

With the server running, add a JSON file to a directory at the root of your project that doesn't contain other files. For the purpose of this example, we'll assume the file is located at content/data/example.json.

{
  "type": "example",
  "title": "Hello Stackbit"
}

Load File into a Page

Open a page in your Next.js project and import the JSON file.

import exampleObject from 'content/data/example.json'

Send that object as props to your page by loading it in getStaticProps or getServerSideProps.

export async function getStaticProps(context) {
  // other code ...
  return {
    props: {
      // other props ...
      example: exampleObject
    }
  }
}

Setup Stackbit

With your Next.js server still running, open a new terminal tab/window and let's get Stackbit set up.

Install Stackbit CLI

Begin by installing the CLI.

npm install -g @stackbit/cli

Add Stackbit Configuration

Next, add the main configuration file stackbit.yaml in the root of your project, with this content:

stackbitVersion: ~0.4.0
ssgName: nextjs
nodeVersion: '14'
cmsName: git
dataDir: content/data

Learn more about Stackbit configuration.

Model Content

Stackbit requires that the content you edit be modeled. Among other necessary functions, this tells Stackbit how to render controls for those editing content.

Stackbit models are placed in the .stackbit/models directory. Let's add a new model called example at .stackbit/models/example.yaml.

name: example
type: data
label: Example Object
fields:
  - type: string
    name: title

Here we've defined a single field for this model: title of type string. See the full model reference here.

Annotate Component

The last thing we need to do is to tell Stackbit how to map content files to elements on the page. This is done through data-sb-* attributes called annotations. Read the full annotations reference here.

In this case we have a data object, which we identify with its local path relative to the root of the project (e.g. content/data/example.json). And then we use a colon and the field name to drill down into it. In this example, the full annotation would be content/data/example.json:title.

Add this value to a data-sb-field-path attribute on the element in which you've rendered the title. Here's an example:

const Page = ({ example, ...rest }) => {
  return (
    <div>
      <h1 data-sb-field-path="content/data/example.json:title">{example.title}</h1>
      ...
    </div>
  )
}

Stackbit Local Development

Now let's take it for a spin. While still running your Next.js server, run the Stackbit development server in a new tab/window.

stackbit dev

This will output something like this:

info: Site directory: /path/to/project/dir
info: Found stackbit.yaml, loading config...
info: Server started. Forwarding requests to: localhost:3000
info: Open https://app.stackbit.com/local/... in your browser

Open the app.stackbit.com/... URL in your browser.

Using the page navigator at the top of the screen, navigate to the page that you've edited and hover over the title. It should now be visually editable!

Next Steps

You've just integrated Stackbit into your site! How cool is that!?

This is just the beginning. And now it's time to get serious. Here are some suggestions on where to go next.

If you get stuck along the way, join the community and we'll help get you back up and running. And see below for some suggested troubleshooting topics.

Separate Code from Content

Separating code from content is a key part of Stackbit. For Stackbit to know how to make content editable, it should not be interwoven among your code.

Learn more about how Stackbit works

Content Modeling

Modeling global data objects is just the beginning. Pages and components can also be modeled, which will enable editors to flexibly build visually-rich pages without the need for a developer.

Learn more here or check out our model reference.

Global Styles

Stackbit has a global styles editor that can enable content editors to change styles across the entire site.

For the best reference, read the how-to modify global styles guide while looking through our starter theme code.

User-Controlled Styles

You can also enable style adjustments within the visual editor. Learn more about user-controlled styles.

Common Questions

Here are a few common questions for folks working through the integration process.