Upgrade to Incremental Preview for Sanity

Over 90% of CMS Previews on Gatsby Cloud are now powered by Incremental Preview:

• Incremental Preview is over 50% more reliable than Legacy Preview
• Scales to multiple simultaneous users
• Provides Preview build history
• Supports Content Sync for a smoother Open Preview experience.

On July 11, 2022, Legacy Preview will be no longer available on Gatsby Cloud. Upgrade before then to maintain Preview functionality for your content editors. Legacy Previews will go offline on this date.

How can I tell if I'm using Incremental Preview?

You'll see the [CLOUD] badge on builds that are using Incremental Preview:

How is Incremental Preview different than Legacy Preview for Sanity?

With Incremental Preview, Gatsby Cloud no longer supports watchMode. While watchMode works well for individual editors or small teams, it does not scale well for larger teams or larger sites.

Doesn't that mean Incremental Preview is slower than Legacy Preview? It used to! Throughout 2022, we shipped features like Incremental Deploys, Direct Data Updates, and Deferred Page Building to make CMS Preview freaky fast. Over 60% of Preview builds are now less than 10 seconds (while still being 50% more reliable than watchMode)!

How-to Upgrade

To complete this upgrade, you'll need to complete the following:

1. Upgrade gatsby
2. Upgrade gatsby-source-sanity
3. Upgrade gatsby-plugin-gatsby-cloud
4. Configure webhooks for CMS Preview
5. Install Sanity Studio extension

1. Upgrade gatsby

First, upgrade to the latest version of Gatsby 3 or Gatsby 4

2. Upgrade gatsby-source-sanity

Upgrade gatsby-source-sanity to version 7.3.1 or later.

npm install gatsby-source-sanity@latest

After upgrading gatsby-source-sanity, make sure you properly configure overlayDrafts and watchMode. overlayDrafts can be enabled for all environments except production. watchMode should only be used when running gatsby develop locally.

With this upgrade, NODE_ENV for CMS Preview changes from development to production.

3. Upgrade gatsby-plugin-gatsby-cloud

Upgrade gatsby-plugin-gatsby-cloud to the latest version. 

npm install gatsby-plugin-gatsby-cloud@latest

4. Configure webhooks for CMS Preview

Sanity has a new system for webhooks which is required for Incremental Preview. Quick Connect for Sanity has been upgraded to support this. To add the correct webhooks, go through the Quick Connect flow:

5. Install Preview Extension for Sanity Studio

One of the major benefits of Incremental Preview is a much smoother Open Preview experience for content editors.

Optionally, install the new Gatsby Cloud extension for Sanity Studio.

That's all folks!

If you haven't already, "Clear cache and restart" CMS Preview.