This Gatsby post was written for Gatsby 3 and is no longer maintained. If you would like to try out SvelteKit or Astro, check out the maintained posts which are based on those. Astro lets you continue to use React but also with partial hydration which can be used to provide an enhanced user experience. SvelteKit offers server side rendering as well as static site generation. See the post on how performance improved switching from Gatsby to Astro for more background.
Using Gatsby Themes is the main topic of this post. First of all, we will look at why they are not what you might think they are. Then we look at their superpowers. Finally we use a Gatsby Theme. Before we do any of that, though, I wanted to explain how I came across Gatsby Themes.
I have been doing the 100 Days of Gatsby Code Challenge . There have been foour previous challenges, which took me from creating a proof of concept site, to building out a fully featured headless shopify store. For the final challenge I had to build a Gatsby Theme then upload my new theme to the NPM repository as a package . If it wasn't for the challenge I probably wouldn't have discovered Gatsby Themes. That's because although I had heard of them, I had assumed (from the name) they were just another way of styling your Gatsby sites. We'll see later that they carry a lot of power. And with that great power comes great responsibility (I made that last bit up 😀 — Gatsby Themes are really powerful though).
First of all, forget the name as it might be a little misleading. You are probably used to Gatsby
starters. They let you set up a site super quick. Let's say you want to create a Gatsby v3 MDX blog using gatsby-starter-climate
. You could create that site and then customise it. You might create a few more sites off the
template for your clients. Imagine you are maintaining all of those sites and a new Gatsby feature
is released making it even faster, but needs a change in the
gatsby-config.js file. A recent example of something similar is the release of the new Gatsby Image API. Anyway,
you have to update each of the sites individually and make the same change on each site to the config
The power of Gatsby Themes is their ability to propagate updates. You can think of them as a Gatsby starter with super powers. As well as the benefits of a starter; being able to build a new site quickly, they bundle configuration. When you create a new site from a Gatsby Theme, you add it as a package to the new site. Now when the configuration of the theme is updated, adding the new capabilities, you only need to update the theme, like you would update a regular package. Once the update is running, you have the new configuration. Gatsby Themes essentially provide reusable building blocks for Gatsby sites.
Gatsby Themes can be used for styling, though this is just a small subset of their tool belt. You might use them to add support for Chakra UI to a website for example and integrate a basic colour theme. You can then customise the theme, using options, on its host sites.
Themes are more powerful that this though. You can use themes to add functionality, like technical SEO meta tags. Now lets say there is some new JSON-LD you need to include in sites to help your google ranking. With a Gatsby Theme, adding it to your site it is easy. Once the theme is updated, you just update the theme package on the host site and you're laughing!
It doesn't stop there. You can add multiple themes to any site. Let's say you want to replace your Disqus comments with a statically generated blog comment system powered by Fauna . You can install a theme which adds that functionality and updates to the theme flow through to your site.
Unlike using a starter, you don't have to clone a repo to use a theme. Instead you add the theme as a dependency package to an existing site. So to get going we will create a new MDX blog site using gatsby-starter-climate . At the command line type: At this stage we have a fully functional site. If we didn't want to use themes we could stop here and customise the site. As an alternative you can apply the theme to one of your existing sites.
We are going to use gatsby-theme-climate . Run this command to install it as a package:
Next we add the theme as a plugin to `gatsby-config.js`. Edit that file to match this:
Finally, we can start the site up, the usual way: Take a look at the site in your browser to familiarise yourself with it, before we add some theme functionality.
In this last step, we add scroll to anchor functionality from the theme, simply by importing a component and using it on our site's home page. Edit `src/pages/index.jsx`: If all has gone well, when you hover over one of those titles, let's say “About me”, you will see a shortcut “#” appear. Click it and the page will scroll so the title is at the top of the screen. If you want to see how to code this functionality up yourself, take a look at the blog post on Gatsby v3 Scroll to Anchor .
How did you find this guide? gatsby-theme-climate is still in its early stages. Some of the next functionality I would like to add is SEO (including Schema.org JSON-LD with open graph images) and site search. Would you find these useful? What other functionality do you think I should target. Keen to hear your views and learn where your pain points are. If you have found this post useful and can afford even a small contribution, please consider supporting me through Buy me a Coffee .
Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. You can get in touch via @askRodney on Twitter and also askRodney on Telegram . Also, see further ways to get in touch with Rodney Lab . We post regularly on online privacy and security as well as Gatsby v3 . Also subscribe to the newsletter to keep up-to-date with our latest projects.