Gatsby recently announced themes, and I got excited. Upon reading through all sorts of write-up on them, my response at first was “huh?” A lot of cool technical speak sounded impressive, but until I started tinkering around with them it was hard to see just how exciting they could be.

Since digging into them I now am of the opinion that with themes, what’s already powerful about Gatsby turns into an even more heavily customizable juggernaut of a tool. This post looks at the advantages of themes from a more beginner, higher-level approach, as well as how a theme can be implemented in a Gatsby site (not how themes are authored, which other resources cover).

Understanding Themes

A Gatsby theme is installed as an npm package, but at its core is setup like any other Gatsby site. Essentially, you can convert one Gatsby project into a reusable building block for other Gatsby projects. This flexibility means you can utilize a theme for multiple sites with use cases like:

Abstracting away configurations setting up Gatsby plugins like gatsby-mdx or gatsby-image

Sourcing data from multiple locations like WordPress, Shopify, or your own microservices

Updating shared functionality once and propagating changes with a simple npm install of your theme

of your theme Making big money cranking out sites for clients faster than the US Economy can go into debt 💰

Thinking of themes as an npm package is useful to understand the power that this abstraction brings to development. Just like package authors of npm can expose more or less of an API to provide greater or less flexibility at different tradeoffs, Gatsby theme authors can provide varying levels of control to users of the theme, providing configuration setup, styling rules, or whole components!

(Imagine how much time you’ll save when you eliminate all the time you spend debugging how you broke node-sass again.)

The Possibilites with Themes

In the words of Jason Lengstorf in a podcast interview on JavaScript to Elm:

A theme is effectively a composable Gatsby config

Just like functions in programming can be composed together like little mathematical nesting dolls, multiple themes can be composed together.

A theme can be installed in another Gatsby project to make a parent theme, a child theme, or even be composed together horizontally to use multiple themes in a single site. You’re able to install a blog theme that houses all the details for your blog, a separate e-commerce theme that can support checkout, and then a styling theme that lays a skin over all the rest of them.

Why use Themes?

This exact topic is covered in this blog post by Kyle Mathews. To sum up some of his points and further his argument, themes provide a higher-level approach to working with Gatsby that abstract away the complex or repetitive parts into a reusable package.

A traditional “one-off” Gatsby sites take a broad array of resources and combines them into a site, but each of those resources is handled individually and has to be added one at a time.

Gatsby starters help to reduce that repetition, allowing you to make a boilerplate of each compose-able plugin or setting you wanted. That starter could be cloned right to where you want to start developing, but what happens when you want to update changes to 20 sites you’ve made from the same starter? The starter has basically been “ejected”, its git history deleted, and you’re left making updates across 20 different repositories with slightly adjusted implementation details.

Gatsby sites consume a variety of resources in what is dubbed the “content mesh”

Themes solve that headache by allowing entire sites and configurations to be packaged up together. You can convert a site into a theme and then rather than pulling in and installing each plugin or asset you want each time you create a new site, the theme can be pulled in that handles all of those for you.

Imagine having the ability to maintain your docs in a Gatsby site by (1) installing a theme (2) filling a folder with markdown files and (3) deploying, using the configuration setup by a theme author. (If you like that idea, great! Because we’re going to do it together 🙌)

A reusable configuration can be packaged up as a theme and implemented in a new site

Themes are not stamped out, cookie cutter sites cloned into an entirely new repo like a WordPress theme. They are upstream pieces of your application that are consumed by your Gatsby project (potentially, many Gatsby projects).