New Gatsby Source WordPress Plugin Now in Beta

Gatsby announced its new source plugin (v4) for WordPress is now in beta. The plugin has been completely revamped to improve headless WordPress setups where Gatsby powers the frontend. It also integrates with Gatsby Cloud to provide real-time previews and incremental builds.

The Gatsby team has had a long journey towards creating an integration for WordPress sites that would satisfy more complex use cases. There are currently three different avenues for using Gatsby with WordPress, each with different benefits and drawbacks:

• Gatsby Source WordPress + WP REST API
• Gatsby Source GraphQL + WPGraphQL
• Gatsby Source WordPress (v4) + WPGraphQL

The first approach relies on the WP REST API to fetch all data (posts, terms, media, etc) and cache the data in Gatsby’s node cache. The second method allows developers to write GraphQL queries to fetch data from the Gatsby cache and render that data in templates.

According to Gatsby engineer and WPGraphQL creator Jason Bahl, the first two approaches are only adequate for basic use cases.

“When you start adding more advanced functionality, such as Advanced Custom Fields Flex Fields, the WP REST API starts to fall apart and become very difficult to use in a decoupled way,” Bahl said. “The WP REST API has a Schema that can allow plugins and themes to extend the WP REST API and declare what type of data any given endpoint will expose. This is helpful for decoupled applications to know ahead of time what kind of data to expect.

“The problem is that plugins and themes can extend the WP REST API without making use of the Schema, or by simply defining field types in the Schema as `object` or `array` Types. This means there’s no easy way for decoupled applications, including Gatsby, to know what to expect from those fields. Gatsby relies on consistent data, and the WP REST API isn’t consistent. The shape of the data returned from endpoints (especially when plugins extend the REST API) is unpredictable and that is problematic for decoupled applications.”

WPGraphQL was created as an alternative to the WP REST API, addressing many of these pain points with its enforced Schema. This benefits decoupled tools like Gatsby because they can introspect the Schema to determine what data is available before requesting any.

“So even cases such as Advanced Custom Fields Flex Fields, where the data being returned could be one of many possible Flex Field Layouts, Gatsby can still know what the possible data is before asking for the data,” Bahl said. “The enforced Schema of WPGraphQL allows decoupled tools to ship with confidence and eliminates entire classes of bugs.”

The Gatsby Source GraphQL + WPGraphQL approach has some improvements over using the WP REST API but was limited in that it doesn’t cache data to the Gatsby node cache. This prevents WordPress sites from being able to utilize Gatsby’s cloud-based commercial offerings for previews and incremental builds. Bahl explained how the new Gatsby Source WordPress plugin (v4) + WPGraphQL is the “best of both worlds:”

It uses WPGraphQL on the WordPress server to expose WordPress data in a Typed GraphQL Schema. Gatsby Source WordPress v4 uses GraphQL Introspection to read the Schema from the WordPress site and builds a nearly identical Schema in Gatsby. It then fetches data using WPGraphQL and caches the data in Gatsby. Users then use GraphQL to interact with the Gatsby cache and get data to render in Components in their Gatsby site.

The new integration gives content creators the ability to click “preview” to see their changes live in the Gatsby-powered site. Publishing no longer requires a full site rebuild. It will simply push out the changes to the affected pages. Changes will be live in seconds, similar to how users expect WordPress to work without the headless integration. The new plugin, combined with Gatsby Cloud, provide a better marriage of the content creation experience with Gatsby’s React + GraphQL developer experience, while delivering fast static pages on the frontend.

If you want to test the beta of the new Gatsby Source WordPress plugin, you can find it (and its dependencies) on GitHub. The WPGraphQL and WPGatsby plugins are also required.