From theme hacking to React
The path into WordPress began with theme development, using Morten Rand-Hendriksen's "Building Themes from Scratch Using Underscores" as a reference and studying his GitHub themes, such as Kuhn and Popper, as models for personal projects. Some plugin and widget work followed, but theming remained the focus. Personal sites were used as archives of learning notes, deliberately discouraging search engines. The habit of documenting every project came from Sara Soueidan's "Just Write."
The shift came with Matt Mullenweg's 2015 State of the Word call to "learn JavaScript deeply" and the later Gutenberg block editor announcement, which framed JavaScript and API-driven interfaces as the future of WordPress. Learning followed road maps from Zell Liew's "Learning JavaScript — where should you start and what to do when you're stuck?" and Robin Wieruch's "JavaScript fundamentals before learning React."
Evaluating React-based WordPress themes
Since the REST API landed in core, several React-based themes appeared, though all seemed experimental:
- Foxhound — built by Automattic engineer Kelly Dwan, listed in the WordPress theme directory with 30+ active installations; its GitHub repository had not been updated in three years. It worked on a test site, but limited JavaScript and React familiarity made it hard to learn from.
- Picard — an Automattic experimental prototype using React and the WP-API; the repository had not been updated in five years, and usage is unknown.
- Celestial — by Muhammad Mohsin, covered in Smashing Magazine's "How To Build A Skin For Your Web App With React And WordPress"; last updated 13 months prior, with no usage information.
Learning Gatsby
Struggling with React routing led to Gatsby, which ships @reach/router as a built-in feature and makes routing straightforward. With small React projects already done, picking up Gatsby came naturally. Its documentation and tutorials are well written, and all eight tutorial parts were completed as "learning by doing." Two further guides helped with build concepts, functionality and assembling a demo site: Justin Formentin's "Guide to Building a Gatsby Site From the Ground Up" and Reactgo's "Build an advanced blog using gatsby and react."
For component styling, the options include local inline CSS-in-JS, styled components and modular CSS, plus Sass through gatsby-plugin-sass. Sass was chosen for familiarity and readability, though the value of CSS modules is acknowledged.
Gatsby and WordPress integration resources
Sites already running on Gatsby report satisfaction, particularly with speed and improved security. For anyone integrating the two, several areas needed attention.
Comments
Gatsby sites are serverless-static, so dynamic features like comments require a client-side service. Some developers defer commenting and interaction to Twitter, others use Disqus. A Northstack tutorial describes in detail how to bring WordPress comments over to Gatsby.
WordPress-inspired Gatsby themes
The Tabor for Gatsby theme, a WordPress port by Rich Tabor, is freely available on GitHub. Two more WordPress-inspired themes arrived through the Gatsby Theme Jam: Alexandra Spalato's Gatsby Theme WordPress Starter and Andrey Shalashov's WordPress Source Theme. In 2019, a team of Gatsby and WPGraphQL developers led by Jason Bahl, Muhammad Muhsin, Alexandra Spalato and Zac Gordon announced a project porting WordPress themes to Gatsby; Zac Gordon told WordPress Tavern it would offer free and paid premium themes. At the time of writing, five themes were listed with no free download.
Starters and ports
The Gatsby starter library lists ten WordPress-compatible starters. Among them is Henrik Wirth's port of the Twenty Twenty theme, stylesheets and fonts included. It is a work in progress with limitations (no support for tags, monthly archives and comments), but it uses the new experimental Gatsby Source plugin for WordPress. Another popular option is gatsby-starter-wordpress by Gatsby Central. On GitHub, Zac Gordon and Muhammad Muhsin's Twenty Nineteen WordPress Gatsby Theme ports the Twenty Nineteen theme.
Experimental plugins
Two GraphQL plugins for WordPress are in development and available only on GitHub. Tyler Barnes's Gatsby Source WordPress Experimental rewrites the current gatsby-source-wordpress plugin to source data through WPGraphQL, paired with a custom WPGatsby plugin that transforms the WPGraphQL schema in Gatsby-specific ways. Peter Pristas is still developing Gatsby WordPress Gutenberg, documented on the GatsbyWPGutenberg Docs site.
Guides
Detailed beginner-oriented how-to material was scarce. Mohammad Mohsin wrote a thorough Smashing Magazine guide on building his Celestial React theme with the WordPress REST API, and another tutorial on porting Twenty Nineteen to Gatsby using WPGraphQL for data sourcing. Two more recent guides were useful:
- Jason Lengstorf's "Migrate Your WordPress Site to the Jamstack," based on his interview with Zac Gordon on the Learn With Jason podcast; a 30-minute version is on egghead.io.
- Henrik Wirth's "Guide to Gatsby WordPress Starter Advanced with Previews, i18n and More," a seven-part series on porting a WordPress site to Gatsby with WPGraphQL — the most detailed guide encountered and suitable for most beginners.
The partially ported site, and what comes next
These resources, plus the experimental plugins and existing Gatsby documentation, made building a personal, partially ported WordPress Gatsby site far easier than working it out alone. The result is still a work in progress, and a complete step-by-step walkthrough of how it was made was slated for publication the following week on CSS-Tricks.
Attention remains on the two experimental plugins, with plans to revisit the project once they are officially released, hopefully in the WordPress Plugin Directory. A tweet thread from Rachel Cherry highlights the open question of porting block editor content into a decoupled WordPress Gatsby theme.
Has anyone successfully used the block editor with a decoupled #WordPress setup? I haven't tried but have heard some rumblings it doesn't work, or doesn't work well. Curious to hear from folks.
— Rachel Cherry (@bamadesigner) May 14, 2020
In a WordCamp Spain 2020 session, Matt Mullenweg said demand for decoupled WordPress sites is growing:
But for people who are building more advanced applications or have some sort of constraint on their website where they need the React frontend, I think the decoupled use case of WordPress is stronger than ever.
Dan Abramov echoed the direction:
This hits the nail on the head. And is 100% matching our long term thinking. Client-side-only is not sustainable. We need to move more stuff to the server, but without sacrificing seamless composition of interactive pieces.
— Dan Abramov (@dan_abramov) May 10, 2020
Speaking with Sarah Gooding of WP Tavern, Gatsby WP Themes project members Zac Gordon and Jason Bahl acknowledged that current Gatsby WordPress themes are directed at businesses and developers and are not suitable for beginners.
Assessment
Current Gatsby WordPress themes are not ready for prime time for users without deep experience. Working on the bleeding edge is exciting, and the area is clearly on the minds of many WordPress users and developers. But ongoing work on the block editor, WPGraphQL and the Gatsby source WordPress plugins makes it hard to predict where things will settle and when it will be safe to use in other contexts. Until then, working on something only to have the API or interface change is a frustrating experience. For personal use, a normal Gatsby site is enough — content can live in Markdown files without the hassles of decoupling WordPress. For larger agency sites, a decoupled solution makes a lot of sense for them and their clients.



