WPGatsby is a required plugin which modifies WPGraphQL and WordPress to work with Gatsby. It enables builds and previews. See Installation for more info about WPGatsby.
Whether you're using a regular CI service like Netlify (I would encourage you to try the free tier of Gatsby Cloud if you are!), or you're using a supercharged CI service like Gatsby Cloud with Incremental Builds, you will set things up the same way.
Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance /wp-admin/options-general.php?page=gatsbyjs or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
You should see the following "Builds Webhook" field at the top of the page:
Enter the Webhook that should be used, a POST request will be sent to the Webhook when content is updated in WordPress.
If you're using Gatsby Cloud, you can find this webhook by navigating to the "Site Settings" tab for your Gatsby instance and then navigating to "Webhook" in the left-side menu.
Below your "Preview Webhook" you should see your "Builds Webhook". Copy this webhook and enter it into your WordPress settings.
Now that your Builds webhook is set up, when content is updated in WordPress your content will update in 4 to 12 seconds if you're using Gatsby Cloud with Incremental Builds, and in 45 seconds to a few minutes (and beyond) if you're using other services! 🚀
Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box. See the feature page on Preview for more information about how Preview works. WPGatsby has been updated to use Gatsby Cloud's new Content Sync service, which is a service that handles the loading view, error handling, and redirection for users that are previewing content. Make sure you've upgraded to the latest versions of WPGatsby, gatsby (v3 or v4), and gatsby-source-wordpress. For documentation about legacy previews where the preview loader used to live on the WordPress side see here.
To get started, set up a Preview instance on Gatsby Cloud.
Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance /wp-admin/options-general.php?page=gatsbyjs or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
You will see 5 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Use Gatsby Content Sync?", "Content Sync URL", "Preview Webhook", and "Preview JWT secret". If you do not see "Use Gatsby Content Sync?" you're on the latest version of WPGatsby and this field isn't needed.
If you don't see this settings page, or you don't see these fields, make sure the latest version of WPGatsby is installed in your WordPress instance.
When this checkbox is checked, WPGatsby will override the functionality of the WordPress "preview" button in the page/post edit screen. Clicking "preview" will open the regular WordPress preview template, but the WP frontend will be replaced with your Gatsby Preview instance.
When this checkbox is checked, WPGatsby will use the new Gatsby Cloud Content Sync service for previews. Instead of WPGatsby handling loading previews and redirecting to the right page, Gatsby Cloud will now do it instead. This is optional but recommended as this will become the default in the future and legacy previews will be removed.
Note: If you do not see this checkbox you're already on a version of WPGatsby where legacy preview has been removed.
This field should be filled with the Content Sync URL of your Gatsby Preview instance.
To find your Content Sync URL, navigate to the "Site Settings" tab in your Gatsby Cloud site dashboard, scroll down until you see the "Content Sync URL", and click to copy the URL displayed there.
You can find your Preview webhook by navigating to "Site Settings" in Gatsby Cloud and then navigating to "Webhooks" via the left-side menu.
This field should be filled for you automatically with a cryptocraphically secure key when you install WPGatsby. If this field is empty, feel free to copy a salt from the WordPress salts generator page and use that as your JWT secret key.
This secret key is used to authenticate short-lived JWT tokens when you're viewing previews from WordPress so a very strong key should be used to prevent security issues.
Now that you've configured WPGatsby for your Preview instance, visit a page or post you'd like to preview, edit it, and press "preview" in the top right corner of the edit screen like you usually would in WordPress. You should see a new tab pop open with your Preview instance and previewed content visible!