Gatsby Themes Pros and Cons

Here is the TLDR. I think for most projects, most of the time, you should use a “starter” when beginning a new Gatsby project. In my opinion Gatsby themes are best suited for two main use cases; large enterprise size projects or a high flow design/development agency.

I say this as someone who has invested a tremendous amount of time and energy into using and learning about Gatsby themes. I even helped write some of the Gatsby docs way-back-when about composing multiple themes together. The core concept behind Gatsby themes remains a powerful framework feature, however my experience has been that the drawbacks of Gatsby themes ultimately become a burden in most small to medium sized projects.

What are Gatsby themes?

Gatsby themes are a way to abstract and encapsulate portions of a website so that they can be maintained and updated independently from the production deploy. Imagine building blocks that are assembled together to form a complete website. A bit like the component model - but at a larger scale.

Themes can be separated into four subtypes; core themes - responsible for dependencies and initial configuration, layout themes - responsible for structural portions of the website like headers and footer, data themes - responsible for data fetching and manipulation, and finally presentational themes - responsible for the visual elements a user sees and interacts with. When I was using themes I often had 3, 4 or 5 different themes composed together in the final project.

Themes are distributed on either a private or public package repository (e.g. npm), added as a dependency, and included in gatsby-config.js just like a plugin. Also like a plugin, Gatsby themes can take a set of options. These options open up a convenient API surface for customizing themes, and these options can be passed down to sibling and child themes as well. With themes everything is neatly tucked into separate packages and managed just like any other project dependency.

Pros and Cons

This story starts and ends with abstraction.

As discussed above, Gatsby themes abstract the code running a website into seperate packages and these packages can be maintained, versioned and updated with total independence. This means that a larger organization can have a set of UI/UX engineers working on a component library inside as a Gatsby theme with their own workflows, repository, and structure. That theme can then be used in not one project, but 5, 10 or 100 projects as is needed. A back-of-the-front team could focus on the data fetching, data shape, and GraphQL mesh; again that team has total independence and can share the progress across hundreds of projects.

Notice that I am referencing teams of people. Large teams. This is the scale where I believe Gatsby themes really start to shine and add value.

At a small to medium sized scale where just a few developers (or one developer) are working across an entire project the abstraction of themes starts to become a hindrance.

Need to update a dependency that is inside of a theme? Well now you need to update the theme, and then go and update the project to reflect these changes. Want to change the branding component? You can use component shadowing to reach into the layout theme and replace components but this starts to create a complicated web of interlinked files and folders.

My experience is that gradually there and more friction points between themes and the production website that just aren’t worth it on all but the largest projects.

For new developers?

I think one other place where Gatsby themes can be useful, is for new developers as they provide a “low-code” entry point for creating a Gatsby website. Here a Gatsby theme can act more like a traditional Wordpress theme; a singular theme that takes in a series of design tokens and settings to allow a moderate level of personalization while abstracting away all the difficult bits of code.

But here is the trouble I see with this. Most developers who are working with Gatsby are either experienced developers already or are developers working to become experienced. We want to muck around in the code ourselves, not have it hidden away. If someone is looking for a low-code or no-code solution there are much better choices out there than Gatsby.

What can be done?

I believe the biggest improvement for themes would be an ejection codemod or cli command. Something like gatsby theme-name eject. This would allow themes to serve as a starting point - and then be left behind from when they start to get in the way. But…this would be super tricky to do…

Another thing you can do is to use a monorepo with yarn workspaces. If you are working with Gatsby themes this is a much smoother and easier setup to work with. You can directly view both the code for the themes and the internal file structure required for component shadowing. It is really annoying to go traipsing through your node_modules folder looking for bits of code.

I think Gatsby was trying to solve some of these friction points with the Gatsby Admin project which has been shelved as far as I can tell. This provided a GUI to surface the file connections, theme options, and folder structures. Something like a Wordpress dashboard for your Gatsby site. I don’t have any details on what happened but I can see why it was put on hold - this just isn’t the developer market that Gatsby serves (right now anyways).

As I said at the outset - Gatsby themes are a powerful and important framework feature. However over time I have come to believe that they shine brightest at a size and scale where abstraction and encapsulation provide critical workflow value. For your next Gatsby project you probably want to pick a starter.

Happy coding!