Using Gatsby Themes: 100 Days of Gatsby

Using Gatsby Themes: 100 Days of Gatsby

Using Gatsby Themes: 100 Days of Gatsby


πŸ“… 100 Days of Gatsby Code Challenge

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).

πŸ˜• What are Gatsby Themes?

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 file.

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.

🎨 So Gatsby Themes aren't Just for Styling?

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.

🧱 How to Use a Gatsby Theme

Using a Gatsby Theme

  1. 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:
    gatsby new mdx-blog-site
    Using Gatsby Themes: gatsby new
    The site has some environment variables which we need to define. Following best practices, these are not stored in the repo. Instead you just need to copy the example file, which is in the repo:
    cd mdx-blog-site
    cp .env.EXAMPLE .env.development
    cp .env.EXAMPLE .env.production
    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.
  2. We are going to use gatsby-theme-climate . Run this command to install it as a package:
    npm install @rodneylab/gatsby-theme-climate
    Using Gatsby Themes: Install gatsby-theme-climate
  3. Next we add the theme as a plugin to gatsby-config.js. Edit that file to match this:
    134 resolve: 'gatsby-plugin-mdx',
    135 options: {
    136 defaultLayouts: {
    137 blog: path.resolve('./src/templates/blog-post.jsx'),
    138 default: path.resolve('./src/templates/blog-post.jsx'),
    139 },
    140 extensions: ['.mdx', '.md'],
    141 plugins: [
    142 {
    143 resolve: 'gatsby-remark-images',
    144 options: {
    145 linkImagesToOriginal: false,
    146 maxWidth: maxImageWidth,
    147 showCaptions: ['title'],
    148 withWebp: { quality: 100 },
    149 tracedSVG: { color: '#5cc8ff', background: '#fff275' },
    150 },
    151 },
    152 ],
    153 gatsbyRemarkPlugins: [],
    154 },
    155 },
    156 '@rodneylab/gatsby-theme-climate',
    157 ],
  4. Finally, we can start the site up, the usual way:
    gatsby develop
    Take a look at the site in your browser to familiarise yourself with it, before we add some theme functionality.
  5. 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:
    import React from 'react';
    import { graphql } from 'gatsby';
    import { Heading } from '@rodneylab/gatsby-theme-climate';
    import PropTypes from 'prop-types';
    import BlogRoll from '../components/BlogRoll';
    import Card from '../components/Card';
    import { PureLayout as Layout } from '../components/Layout';
    import { PureSEO as SEO } from '../components/SEO';
    export default function Home({ data }) {
    return (
    <SEO data={data} title="Home" metadescription="Climate - Gatsby v3 Starter for MDX Gatsby Blog" />
    <Layout data={data}>
    <Heading as="h1" hash="climateGatsby3Starter">Climate &mdash; Gatsby 3 Starter</Heading>
    <Heading as="h2" hash="mdxBlogStarter">Gatsby 3 Starter for MDX Blogs</Heading>
    <Heading as="h2" hash="aboutMe">About me</Heading>
    I live and breathe analogue photography. I show you my favourite analogue film cameras
    on this site. Hopefully if you are not into analogue photography yet, some of my
    enthusiasm will rub off onto you.
    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.
    Using Gatsby Themes
    You can customise themes, but we won't go into that here. If you want to learn more, read about Shadowing Gatsby Themes on the Gatsby site .

πŸ™πŸ½ Feedback

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 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.