If your site uses a content management system (CMS), Gatsby Cloud provides a tool to easily preview content changes and collaborate with content editors. When you add a site to Gatsby Cloud, you will find CMS Previews under the CMS Preview tab of the Site Overview page.
A CMS Preview is a development build of your site that enables you to make changes in your CMS and see those changes take effect in real-time.
Using CMS Previews requires connecting your site to one of the supported CMSs. Check out the Connecting to a Content Management System tutorials for more information on how to configure your site for CMS Previews.
How CMS Previews are Triggered
A CMS Preview build may be triggered when any of the following events occur:
- a change in the connected CMS (such as an autosave while typing, save, or publish action)
- a Git commit to the production branch configured in site settings
- manually clicking the Trigger Build or Restart Preview button in the Gatsby Cloud user interface
- a POST request to the Preview Webhook
How CMS Previews are Built
There are two CMS Preview build approaches; these are the legacy preview experience and the new incremental preview build.
This is the default preview builder. It is a production build of your site using preview data as specified by your environment variables. The main benefits are:
- fast updates after initial build
- all successful preview builds are always available
- support for the preview status indicator on Gatsby v3
All other CMSs integrations for Gatsby Cloud support incremental previews. Of these, the following require a specific source plugin version:
- WordPress: gatsby-source-wordpress ≥ 5.2.3
- DatoCMS: gatsby-source-datocms ≥ 2.6.15
- Sanity: gatsby-source-sanity ≥ 7.3.2
Incremental Previews are those noted with the [CLOUD] badge:
This preview builder is only used where incremental previews are not possible. The build process is similar to
gatsby develop in local development. It is subject to resource timeouts and the preview will not be available until the next build completes after a timeout occurs.
Some CMSs support a preview extension that enables you to view your CMS Preview build without having to leave your CMS. Preview extensions are available for:
Check out the Preview Extensions tutorials for more information. WordPress preview loader doesn't support password-protected preview instances.
You can disable Preview by visiting Site Settings -> Preview and uncheck Enable CMS Preview builds.
If your preview fails to build for 10 consecutive builds, Gatsby Cloud will automatically disable the Preview.