How Stackbit Works

And end-to-end guide on how things work.

You can put many of the concepts you'll learn in this guide into action by following the getting started tutorial. Or you can watch the video below for a shorter introduction.

00:0000:00
How Stackbit Works (View on YouTube)

This guide is focused on technical details and is written for developers. It explores the structure of a website and the flow of content through both Stackbit and the code that powers your website. If you aren't technical, we recommend creating a new project to see Stackbit in action.

Creating a visual editing experience with Stackbit for your site requires understanding how Stackbit works. By working through this guide, you'll learn the following:

  • Bringing Stackbit into Your Site: Stackbit enables you to create a visual editing experience for your site. It plays no role in your production application.
  • Content-Driven Development: Stackbit's sole requirement is that your site's content is structured and separate from code, which provides the ability to create reusable and composable pages and components.
  • Working Modes: Local development helps enable visual editing with minimal friction, prior to creating a Stackbit project, which unlocks collaboration and custom workflows for content editors.
  • Stackbit's Visual Editor: The component parts on the screen and the application behind it provide the basis for understanding how content editing works.
  • Content Editing Flow: When a content property is changed, the content is updated in its source, and the new value is reflected on the screen.
  • Highlighting & Inline Editing: To make content editing even easier, developers can make it possible for editors to click on elements on the site and edit them inline, leading to a slightly different content flow.
  • Creating a Stackbit Project: When it's time to bring content editors into a project, creating a Stackbit project will provision the appropriate services and provide customizable editing workflows.

Bringing Stackbit into Your Site

The first and most important thing to understand about Stackbit is that it plays no role in your production application. As you'll learn later, Stackbit's visual editor works when your site is running in development mode. That means that the packages, code, and configuration can be made contextual to your development environment and never have to make it to production.

Bring Your Own Site

Stackbit does not require that you start from scratch, either. Many developers already have a website that works just fine but lacks a superior visual editing experience. As long as your project meets the basic requirements, it can be used as-is with Stackbit. After some configuration, editing can come to life very quickly.

Starting from Scratch

Other developers begin working with Stackbit on a new project. In these cases, we have starter projects that come configured and ready to build.

Third-Party Services & Tooling

Because your site is your site and not owned or controlled by Stackbit, you are welcome to use any third-party services, tools, or custom workflows that you prefer.

There are limitations on tools that directly tie into the editing experience, such as your CMS or media service provider. Contact us for details.

Basic Requirements for Stackbit Sites

Stackbit carries only a single requirement that affects the code running in production: content must be structured and separated from code. If you're using an API CMS, the requirement is generally met. If using local files for content, they must exist in their own directory and have a predictable structure.

Although technically anything is possible, Stackbit currently works best with Node-based site frameworks. Contact us for details.

Content-Driven Development

The only real requirement that affects your site's code is that content must be structured and separated from code. Along with some configuration, that's enough to get the basics of Stackbit to work.

To make pages and their components editable, they must be represented by a data model in the content source. Learn more about how Stackbit works with structured content.

Visual editing can be made powerful and flexible when introducing composable pages with structured content. Or, when the structure of a set of pages is predictable, you can streamline the editing process using templates.

Working Modes

Stackbit has two working modes:

  • Local Development: Stackbit's visual editor application proxies a preview of your site's development server, locally on your machine. Think of this as a development environment for building out a visual editing experience for your content creators.
  • Stackbit Project: Stackbit hosts the visual editing experience, enabling you to add collaborators and custom workflows. Think of this as the production environment for visual editing.

Most Stackbit projects begin with developers working locally to use Stackbit to build a visual editing experience for their site. When they are ready to get content editors involved in the project, that's when it comes time to create a Stackbit project.

While we'll explore both of these modes through this guide, we'll default to talking about local development, but call out notable difference with Stackbit projects where necessary.

Stackbit's Visual Editor

Running Stackbit in local development mode means running two processes:

  • Site Development Server: The server that you would typically run while writing code.
  • Stackbit Dev: Using our CLI, you can run the Stackbit development server on your machine. This outputs a URL you can visit to launch Stackbit's visual editor.

Visual Editor Controls & Site Preview

After authenticating, the Stackbit application will open the visual editor for your project, which consists of various editing controls along the left and top of your screen, along with a preview of the you're running locally in development.

Stackbit Dev - App Layout
Stackbit Dev - App Layout

Although there is some intricacy in how this all fits together, it's most important to understand the following points:

  • Editing controls (everything that isn't your website) are all being run from the Stackbit application (app.stackbit.com).
  • Stackbit Dev launches a local server (on port 8090) that combines your development server, along with a script to enable visual editing, and some server-side functionality for storing and retrieving content. (More on content flow below.)
  • The preview is just an <iframe> loading the content of localhost:8090.

Stackbit Projects & Containers

The architecture when running Stackbit's visual editor on a hosted Stackbit project is similar. But rather than the visual editor proxying traffic to a server running locally, it points to a Docker container.

That container is responsible for cloning and running your site in development mode, while injecting the visual editing script, and providing necessary back-end functions for retrieving and storing content.

Content Editing Flow

There are two ways to edit content with Stackbit. The first (and simpler) is in using the page editor panel on the left side of the screen. (We'll cover inline editing in the next section.)

Basic Content Editing from Editor Panel

Here's what happens when a content editor makes a change to content in a field in the Stackbit visual editor:

Stackbit Content Update Flow
Stackbit Content Update Flow
  1. The visual editor notifies Stackbit Dev (or the container, if using a Stackbit project) of the content change.
  2. Stackbit Dev updates the appropriate content in the content source.
  3. The visual editor app notifies the visual editor script (via postMessage to the <iframe>), which leads to automatically updating content on your site, optimized for your chosen site framework.

There's a bit of detail missing from this process. We'll uncover piece-by-piece as we progress through this section.

Reactive Content Updates

Stackbit Dev also listens for content changes coming from the content source (API CMS).

Reactive Content Updates
Reactive Content Updates

When content is updated, whether by you or another user, here's what happens:

  1. Stackbit Dev receives the update from the content source (via polling).
  2. Stackbit Dev notifies the visual editor app of the content change. The app updates the appropriate field values.
  3. Like above, the visual editor app notifies the preview's visual editing script of the change, leading to updated content on the page.

Automatic Content Reload

When Stackbit updates the content on your page (#2 in the graphic above), this is what we call automatic content reloading.

How exactly this works is determined by the ssgName option in your configuration file. For example, if using Next.js, Stackbit knows to call router.replace() to reload the content without a full page reload.

You can also override this behavior by listening for an event sent by Stackbit when content updates. Learn more about automatic content reload.

Detailed Content Flow

With that, let's break each of these steps up and look at the entire flow of a content update, originating with a change to a field in the visual editor app.

Detailed Content Update Flow
Detailed Content Update Flow
  1. Content editor makes a change using the field editor panel. The visual editor app notifies Stackbit Dev of the change.
  2. Stackbit Dev's CMS utilities update content in the content source.
  3. Stackbit Dev also has a content listener which polls the content source for changes. After content is updated, it retrieves the new content.
  4. Stackbit Dev sends the updated content to the visual editor app.
  5. The app notifies the visual editor script (in the preview <iframe>) of the change (via postMessage). The script triggers an efficient content reload for your framework (as described in auto content reload, above).
  6. Your dev server reacts to this trigger by retrieving content from the content source. This is the code you've written to fetch and render content for your pages and components.
  7. After retrieving that content, your dev server reloads in the DOM, making the updated content appear in the <iframe> preview.

Working with Draft Content

When working with content that lives in an API CMS, Stackbit works exclusively with content in a draft state, a nearly universal feature provided by headless CMS providers. This enables editors to update content and preview in real-time without affecting your production site.

Using a Local Content Source

If using local files as the content source (Git CMS), the updating content flow is similar, but the effect is slightly different:

  • Local Development: Files are changed directly by Stackbit Dev.
  • Stackbit Project: Every content change becomes a Git commit on a preview branch, and then gets pushed to the content source (e.g. GitHub).

Highlighting & Inline Editing

The more advanced form of editing is inline editing. With inline editing, content creators can hover over elements in your site preview and change the content inline, all without expanding the editors controls in the left panel. This is often the preferred and most convenient form of editing, though it takes some code to make it work.

Visual Highlighting for Inline Editing
Visual Highlighting for Inline Editing

How Highlights Work

Highlights — the blue boxes that appear around editable content — are determined by code. Developers are in full control and tell Stackbit exactly how to handle editable content on the preview. We call this process annotating.

Every editable element is enabled by annotating elements with two key pieces of information:

  • The ID value of the content object.
  • A chained path to the individual property within the content object.

This works by using a series of data-sb-* attributes on the HTML elements on the page.

Consider our composable page example in which we showed a page with a series of sections, the first of which was a Hero section with a heading property.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
{
  "id": "home-page",
  "type": "ComposablePage",
  "sections": [
    {
      "type": "HeroSection",
      "heading": "Page Heading"
      // ...
    }
    // ...
  ]
}

To make that heading editable inline, you have to annotate the HTML. Here's a simple example:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
<!-- Page wrapper -->
<main data-sb-object-id="home-page">
  <!-- Wrapper around sections -->
  <div data-sb-field-path="sections">
    <!-- Wrapper for Hero component -->
    <div data-sb-field-path=".0">
      <!-- Hero component content -->
      <h1 data-sb-field-path="heading">...</h1>
      <!-- ... -->
    </Callout>
    <!-- ... -->
  </Callout>
</main>

Notice the following:

  • data-sb-object-id matches the id property of the page (home-page). Along with additional content source configuration, this is what tells Stackbit how to find the appropriate record in the CMS.
  • Wrapping elements have a data-sb-field-path attribute that works to form a path to the property within the content object. In this example, that path becomes sections.0.heading.

Stackbit then uses the ID along with the HTML hierarchy to build a full path to the content — home-page:sections.0.heading — and knows how to highlight the element and update its content accordingly.

Here's how it comes together:

How Annotations Work
How Annotations Work

Learn more about annotations.

Content Flow Differences with Inline Editing

When a change is prompted from inline editing, the content flow is nearly identical to the detailed flow discussed earlier.

Detailed Adjustments for Visual Editing
Detailed Adjustments for Visual Editing

The only difference (marked as * above) comes at the beginning of the flow. The visual editing script notifies the visual editor app (again via an iframe message) about the change. The rest of the flow then continues as before.

Step #7 may feel odd in this case, given that we shouldn't need to update the preview when the content has already been updated. There are two reasons why we still follow this update flow:

  1. Stackbit doesn't know how to render all changes. Inline text is one thing, but if the change was to add a button — Stackbit can prompt the content change, but needs to wait to react to how your site handles the rendering of that change.
  2. If another user is editing the site, we also want to show that content has changed, so that they can continue working with the most updated content.

Creating a Stackbit Project

When it comes time to bring content editors and other collaborators into your Stackbit project, you can create a Stackbit project.

This unlocks the ability to invite others to collaborate on the project, who can then preview and publish content changes for your site.

While we've already discussed the architectural differences between Stackbit projects and local development, there are a few other concepts necessary to understand when moving to a Stackbit project.

Stackbit Project Requirements

Stackbit is much more lenient about what you can do locally than when creating a collaborative project. Please note the following:

  • Remote Repository: Your code must live in a GitHub repository. Other providers are available for paid plans. Contact us for details.
  • Content Source: Content should be in place in a supported content source. Local content is available for free plans, while API CMSs are available for paid plans. Contact us for details.
  • Site Framework: The project must use a supported framework. Next.js is available for free projects, while more are available for paid plans. Contact us for details.

Provisioning Services

When first deploying, Stackbit provisions services based on your site and configuration. In most cases, you'll have the majority of your third-party services already configured and working. In those cases, Stackbit provisions the following:

  • Production Site: Stackbit automatically deploys your site to a [site].stackbit.app site on Netlify.

  • Container: Stackbit creates a container that powers the editing experience for your site, as mentioned throughout the guide.

Publishing Remote Content (API CMS)

Stackbit projects enable content editors to publish content. This process uses the Stackbit API to convert all draft content in the CMS into a published state. Webhooks within the CMS then typically kick off a new build of the site, although this is up to your preference and configuration within the CMS and your remote Git host.

Publishing Local Content (Git CMS)

If using local Git CMS, publishing means that Stackbit merges the working branch (default: preview) into your repo's default branch and pushes the merge commit to the content source (e.g. GitHub).

A push to the default branch typically triggers webhooks, which then kick off a new build of your site in your build and hosting provider (which is Netlify if using Stackbit's default deployment).

Next Steps

This concludes the overview of how Stackbit works. Here are a few suggestions on what you can do next:

  • Follow the tutorial if you haven't. This provides a quick way to put some of these concepts into action.
  • Begin integrating Stackbit with your existing site or create a new site with npx create-stackbit-app.
  • Join the Discord community to get support and provide feedback about anything related to Stackbit (including this document).

And please feel free to contact us directly at any point.