Two-Way Content Sync

Stackbit provides a two-way content-syncing mechanism between all of your content sources. It enables your editors to make changes with Stackbit, while also listening for changes in the source to ensure you're previewing the most recent draft content at all times.

Stackbit's Visual Editor#

Understanding the content flows requires prerequisite knowledge on the mechanisms at work while content is being updated.

Development Processes#

As you may have learned in How Stackbit Works, running Stackbit in local development mode means running two processes:

• Site Development Server: The server that you would typically run while working on your site locally.
• Stackbit Dev: The process running on your machine that enables you to run the Stackbit visual editor while in development.

Stackbit Dev Application#

Although there is some intricacy and nuance in the various components of the Stackbit application, it's most important to understand the following points:

• Editing controls (everything that isn't the preview of your website) are 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. (This is the vital piece in content-updating flows shown below.)
• The preview is just an <iframe> loading the content of localhost:8090.

Differences with Cloud Projects#

The flows we'll show throughout this document assume you're working in local development. Thus, the critical piece is labeled as Stackbit Dev.

To translate this to how content is updated in a cloud project, simply replace Stackbit Dev with a virtual container running in the cloud. The process itself is nearly identical.

Working with Draft Content#

To ensure that editors working concurrently see the same content at the same time, Stackbit relies on a two-way content sync mechanism that stores all changes back to the source, while constantly listening for updates made to the source.

As a result, every editor works with content as it exists in the most recent draft state in the source of truth.

Content Editing Methods#

Before we get into the flows, let's look at the content-editing methods with Stackbit:

• Content Editor: A more traditional CMS-like method for editing any one of your content models without the preview context.
• Page Editor: Field-based editing within the context of a specific page, and with real-time updates to the preview.
• Inline Editing: Editing inline and in-context using highlights on the preview.
• Source Editing: Using some other method to update content at the source.

Each of these actions prompts a specific content update flow that is explained in further detail below.

Content Editor#

The content editor is the most traditional means of editing content with Stackbit. It prompts the simplest update flow in Stackbit, because there is no preview to update. Learn more about the content editor.

Page Editor#

The page editor is a form-based editor, but appears within the context of the active page in the preview window. The content flow here is slightly more advanced, as it requires that the preview also be updated when the content changes at the source.

Inline Editing#

Inline editing is the most advanced form of editing. It enables editors to click on content within the preview and edit in-place. Stackbit must then update the content in the page and content editor, while also updating the source and the preview (after the highlight is blurred).

Editing at the Source#

Finally, you're always free to edit content outside the context of Stackbit. For example, if you are storing content in Contentful, you can still update content in Contentful. Stackbit listens for content changes and pulls them into each of the editing techniques above in real time.

Some content sources also have other means of updating content, such as through an API. Stackbit will also pick up these changes to reflect the most recent draft content in the preview and editor panels.

Content Sync Flows#

Let's look Stackbit's standard two-way content syncing mechanism, which saves content back to the source, while also listening for changes made from other Stackbit users or content updates made directly to the source.

This method serves both the standard content editor and page editor, with a slight difference, as noted below.

Sending Changes to the Source#

Regardless of whether you're working with the content editor or page editor, here's what happens when you make a change to a form field value in Stackbit while working locally:

1. The visual editor notifies the Stackbit dev server 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, which we'll fill in below.

Reactive Content Updates#

Stackbit Dev also listens for content changes coming from the content source. This is how the values within both the form fields (content and page editing) and the preview (page editing only) stay up to date.

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

1. Stackbit Dev identifies 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.

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 form field.

1. A change is made to a form field. 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's content listener polls the content source for changes. After content is updated in the source, Stackbit Dev 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, below).
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 the DOM, making the updated content appear in the <iframe> preview.

Working with File-Based Content#

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

• Local Development: Files are changed directly by Stackbit Dev, but left uncommitted on your local machine.
• Stackbit Project: Every content change becomes a Git commit on the working branch, and is then pushed to the content source (e.g. GitHub).

Automatic Content Reload#

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

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

For custom usage or frameworks not yet supported, you can also override this behavior by listening for an event sent by Stackbit when content updates. Learn more about automatic content reload.

Inline Editing Content Flow#

When a change is made inline (rather than a form field), the content flow is nearly identical to the detailed flow discussed above.

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

Handling DOM Reloading#

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.

But there are two reasons why this is necessary:

• Stackbit doesn't know how to render all changes. Inline text may seem easy, 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.
• 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.