This page has moved to the Gatsby monorepo!
Hi there! 👋 thank you so much for being a beta/alpha tester of this plugin! You've helped us bring a much more stable WordPress integration to Gatsby and we're very thankful for that!
We've shipped this plugin as gatsby-source-wordpress@4.0.0.
gatsby-source-wordpress-experimental is now deprecated.
Please upgrade by npm/yarn installing the latest version of the stable plugin and updating your gatsby-config.js to include the stable plugin name.
We've chosen this point to release this plugin as a stable release not because there are no bugs (all software has some bugs), but because this plugin is far more stable than the last major version of gatsby-source-wordpress.
Note that we will continue fixing Github issues you've opened in the -experimental repo - those are not forgotten and will be transferred to the Gatsby monorepo.
Thank you! 💜
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.
Wether 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 as long as your Gatsby pages have the corresponding node id as part of their pageContext. See this starter's gatsby-node.js for an example of how to set up your Gatsby pages. See the feature page on Preview for more information about how Preview works, considerations you should keep in mind while writing Preview-ready templates, and how to debug Preview templates.
To get started, set up a Preview instance on Gatsby Cloud or set up your self-hosted Preview instance. If you want to try out Preview but aren't sure wether you want to subscribe to Gatsby Cloud or self-host, you can start a free 2 week Gatsby Cloud trial with no credit card to help you make up your mind!
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 4 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Preview Instance", "Preview Webhook", and "Preview JWT secret".
If you don't see this settings page, or you don't see these 4 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.
This field should be filled with the public frontend URL of your Gatsby Preview instance.
To find your Preview Instance URL, navigate to the "Preview" tab in Gatsby Cloud, wait for your first Preview build to complete, and then copy the frontend URL from above the build history list in the center of the page.
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!