Gatsby WordPress Starter is a Gatsby v2 boilerplate that turns a WordPress site into a static Gatsby site by sourcing content through the gatsby-source-wordpress plugin.
What is the Gatsby WordPress Starter?
It is a Gatsby v2 starter template forked from the gatsby-starter-netlify-cms project and modified to replace Netlify CMS with WordPress as the content source. The template takes a WordPress installation (with posts, pages, and tags) as input and produces a static Gatsby site as output, using the gatsby-source-wordpress plugin to pull data into Gatsby's GraphQL layer. It runs on the Gatsby build system and was created by the GatsbyCentral crew, with contributions from tomByrer and dajocarter.
Key Features
The starter includes a set of defaults for connecting Gatsby v2 to WordPress and for trimming CSS output.
- WordPress as a headless CMS — The gatsby-source-wordpress plugin connects to any WordPress site's API, so posts, pages, and tags are fetched and available as GraphQL queries.
- Forked from Netlify CMS starter — Based on the gatsby-starter-netlify-cms, this starter swaps out Netlify CMS for WordPress while retaining the project structure and many defaults.
- Bulma styling with purgecss — The starter uses the Bulma CSS framework, and gatsby-plugin-purgecss removes unused styles, cutting the Bulma contribution from about 170KB per page down by roughly 90%.
- Quick setup via Gatsby CLI — A new project can be created with
gatsby new NAME https://github.com/GatsbyCentral/gatsby-starter-wordpress, then editgatsby-config.jsto change thebaseUrlto your WordPress site. - Demo site and sample content — A live demo is available at https://gatsby-starter-wordpress.netlify.com/, and a WordPress XML export can be imported to replicate the demo content in your own WordPress installation.
- Permalink validation — The starter explicitly requires WordPress permalinks to be set to "Post Name" rather than "Plain", and needs at least one post, one page, and one tagged post to avoid crashes.
Who should use the Gatsby WordPress Starter?
This boilerplate suits developers and teams that want WordPress as a content backend with Gatsby as a static front-end.
- WordPress developers who want to migrate an existing site to a static Gatsby front-end while keeping the WordPress admin for content editing.
- Agency teams building client sites with a headless CMS architecture, where WordPress handles content and Gatsby handles rendering and performance.
- Gatsby beginners looking for a working reference implementation that shows how to wire gatsby-source-wordpress into a Gatsby v2 project.
What can you do with it?
With this starter you can go from a WordPress URL to a Gatsby static site in a few steps.
- Migrate a WordPress blog to a static Gatsby site with the same posts and pages, gaining Gatsby's build-time optimizations and static hosting benefits.
- Set up a headless CMS demo quickly, using the provided demo content XML to see how posts and tags map into Gatsby pages.
- Use as a foundation for a custom Gatsby v2 site, since the starter already configures the WordPress source plugin, routing, and Bulma-based styling.
How does it work?
The setup requires running the Gatsby CLI, editing one config file, and ensuring WordPress meets a few conditions.
- Run
gatsby new NAME https://github.com/GatsbyCentral/gatsby-starter-wordpressto scaffold the project. - Edit
gatsby-config.jsand change thebaseUrlvalue to your own WordPress site's URL. - Ensure WordPress permalinks are set to "Post Name" (not "Plain") and that the site has at least one post, one page, and one tagged post.
- Build with
gatsby build; the gatsby-source-wordpress plugin fetches content and Gatsby statically generates pages.
Known limitations
The starter ships with a few documented caveats that affect how you structure your WordPress content.
- The starter is based on the Netlify CMS template that uses Bulma, which adds roughly 150KB to every built page before purgecss trims it.
- Your WordPress site must contain at least one post carrying at least one tag, otherwise the starter crashes during build.
- Nested pages and categories are flattened: a WordPress page like
/about/team/renders as/team/in Gatsby, and the same applies to categories. - The project is no longer actively maintained; the repository description asks for a new maintainer.
FAQ
Does this starter work with Gatsby v3?
The starter is built for Gatsby v2, as stated in its title. Compatibility with Gatsby v3 is not documented, so you may need to upgrade dependencies yourself.
Why does the build crash if I don't have a tag on a post?
The starter's code assumes at least one post has a tag to build the tag pages. Without any tags, the tag template has no data and the build fails. Adding a tag to any single post resolves the crash.
How do I get the demo content?
You can download the WordPress XML export from https://wpdemo.gatsbycentral.com/gatsbystarterwordpress.WordPress.2019-09-12.xml and import it into your WordPress site using the WordPress importer tool.
Can I get support via GitHub issues?
The maintainers ask that support questions be posted on StackOverflow or similar sites instead. GitHub issues are only for bug reports that include a reproduction.
Is this starter free?
Yes, the starter is open-source under the GitHub repository, and there is no mention of any paid license or subscription.
