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! 💜
From what we've seen migrating is a fairly painless process as the GraphQL schema structure is not too different from older Gatsby WordPress source plugins.
Note: If you're using Gatsby Cloud and you have gatsby-source-wordpress@v3 and gatsby-source-wordpress-experimental installed in the same site, only the experimental plugin will receive webhook updates when updating content.
Graphiql is your best friend when migrating from the last major version of this plugin. Run gatsby develop and visit http://localhost:8000/___graphiql
Any node list queries such as allWordpressPage { nodes { title } } will need to be updated to match the new WordPress types in the Gatsby schema. The new pattern for type names is Wp and then the capitalized type such as Page. So to replace the node list query above, you would write allWpPage { nodes { title } }.
Since v3 used the WP REST API and v4 uses WPGraphQL, the data shape and available fields for each type will vary. For example featured_image in v3 becomes featuredImage in v4. Many of the core WordPress data fields remain the same, but if you're using any custom data, or fields added by extensions to access additional data (like ACF fields), you will need to use Graphiql to determine what the new data shape will be. If you find you're missing data, you may need to install a WPGraphQL extension to add that data to the schema. In most cases you will find that you have access to more data than before! But commonly, the WPGraphQL ACF extension will need to be installed.
If you have any custom code which you've added to make connections between nodes work in v3, you will get to delete that code (yay!) because WPGraphQL has excellent support built in for connection fields between nodes (for example Page.author or User.pages).
You're in luck! 🍀 This will likely be a very easy migration!
gatsby-source-graphql works in a very similar way to this plugin. What that means is your GraphQL queries will be nearly identical.
You will need to remove the wp root field which wraps around your gatsby-source-graphql queries. You will also need to modify the names of fields you're querying to get access to WordPress nodes.
For example, if you're querying for a list of pages:
{
wp {
pages {
nodes {
title
}
}
}
}You can modify your query so that the root field is in this pattern: allWp[fieldTypename] and the wp wrapper is removed.
So your query would change to look like this:
{
allWpPage {
nodes {
title
}
}
}
Any inline fragments will need to be updated since type names have changed. Use Gatsby's Graphiql at http://localhost:8000/___graphiql with gatsby develop running to determine how your inline fragment typenames should be modified.
If you're using any plugins or additional schema customization code to enable the use of gatsby-image, you can delete that code and uninstall those plugins. gatsby-source-wordpress@v4 handles that for you out of the box!
If you're using any WPGraphQL input arguments, you will need to rethink how you're accessing data. Input arguments are not currently supported as finding a good way to cache data with various input arguments is very tricky. We have some ideas on supporting this but for now it's not supported.