Two-way content sync
Netlify Create stores content back to the appropriate source, while also listening for changes from each source.
Netlify Create provides a two-way content-syncing mechanism between all of your content sources. It enables your editors to make changes with Netlify Create, while also listening for changes in the source to ensure you're previewing the most recent draft content at all times.
# Netlify Create'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 Netlify Create works, running Netlify Create in local development mode means running two processes:
- Site Development Server: The server that you would typically run while working on your site locally.
- Netlify Create Dev: The process running on your machine that enables you to run the Netlify Create visual editor while in development.
# Netlify Create dev application
Although there is some intricacy and nuance in the various components of the Netlify Create 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 Netlify Create application (create.netlify.com).
- Netlify Create 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 (Netlify Create Dev).
To translate this to how content is updated in a cloud project, replace Netlify Create Dev with a virtual container running in the cloud. The process itself is nearly identical.
# Work with draft content
To ensure that editors working concurrently see the same content at the same time, Netlify Create 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.
Need a different workflow?
If you have a need to work with content in some other way, we can likely accommodate your workflow. Send us a message to learn more.
# Content editing methods
Before we get into the flows, let's look at the content-editing methods with Netlify Create:
- 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 Netlify Create. It prompts the simplest update flow, 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. Netlify Create must then update the content in the page and content editor, while also updating the source and the preview (after the highlight is blurred).
# Source editing
Finally, you're always free to edit content outside the context of Netlify Create. For example, if you are storing content in Contentful, you can still update content in Contentful. Netlify Create 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. Netlify Create 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 at Netlify Create's standard two-way content syncing mechanism, which saves content back to the source, while also listening for changes made from other Netlify Create 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.
# Send 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 Netlify Create while working locally:
- The visual editor notifies the Netlify Create dev server of the content change.
- Netlify Create Dev updates the appropriate content in the content source.
- The visual editor app notifies the visual editor script (via
postMessageto 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
Netlify Create 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 Netlify Create user, or at the source, here's what happens:
- Netlify Create Dev identifies the update from the content source (via polling).
- Netlify Create Dev notifies the visual editor app of the content change. The app updates the appropriate field values.
- 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.
- A change is made to a form field. The visual editor app notifies Netlify Create Dev of the change.
- Netlify Create Dev's CMS utilities update content in the content source.
- Netlify Create Dev's content listener polls the content source for changes. After content is updated in the source, Netlify Create Dev retrieves the new content.
- Netlify Create Dev sends the updated content to the visual editor app.
- The app notifies the visual editor script (in the preview
<iframe>) of the change (viapostMessage). The script triggers an efficient content reload for your framework (as described in automatic content reload, below). - 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.
- After retrieving that content, your dev server reloads the DOM, making the updated content appear in the
<iframe>preview.
# Work 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 Netlify Create Dev, but left uncommitted on your local machine.
- Netlify Create 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 Netlify Create 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, Netlify Create 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 Netlify Create 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.
# 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:
- Netlify Create doesn't know how to render all changes. Inline text may seem easy, but if the change was to add a button — Netlify Create 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.
Did you find this doc useful?
Your feedback helps us improve our docs.