DEV Community

Cover image for How to Turn an Existing Gatsby Site Into a Theme
Laurie
Laurie

Posted on • Originally published at tenmilesquare.com

How to Turn an Existing Gatsby Site Into a Theme

#javascript #webdev #tutorial #productivity

If you haven't caught the live stream where we did this, check it out here! While this post is informative and will cover most of what we worked on, I genuinely cannot reproduce that level of comedy and banter. @jlengstorf is a blast.

Also, full credit to @likeomgitsfeday whose site was the original inspiration (and architecture) for mine!

With that as a primer, let's dig into the code.

Project Setup

My project exists in a slightly cluttered personal directory. So to start things out, we're going to move it into a new folder. The incredibly named, site-and-stuff. This isn't strictly necessary, it just helps for organizational purposes.

From there, it's time to setup the theme project and associated yarn workspace.

Initialize Theme

Inside site-and-stuff I'll make a directory called gatsby-theme-speaking-yaml. That means that site-and-stuff currently contains that theme project and my original site project, gatsby-laurieontech.

Now we want to initialize my theme project. To do this, we'll run the following command inside gatsby-theme-speaking-yaml.

yarn init -y
Enter fullscreen mode Exit fullscreen mode

This creates a package.json with some existing information. However, we also want to add a few additional items, author and keywords. The whole thing ends up looking like this.

{
  "name": "gatsby-theme-speaking-yaml",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "author": "Laurie on tech",
  "keywords": ["gatsby", "gatsby-plugin", "gatsby-theme"]
}
Enter fullscreen mode Exit fullscreen mode

Note that our main points to index.js. This file doesn't currently exist so we need to create it. It doesn't need any content at the moment, so we'll just put in a comment for now and that will be sufficient.

Setup Workspace

We also need to create a package.json in our root directory, site-and-stuff. In this case we'll just create the file and add some information manually. It ends up looking like this.

{
  "private": true,
  "workspaces": ["gatsby-laurieontech", "gatsby-theme-speaking-yaml"]
}
Enter fullscreen mode Exit fullscreen mode

To test out that this worked, you can run the following command.

yarn workspaces info
Enter fullscreen mode Exit fullscreen mode

Install Theme Into Site

Next, we'll add our theme to our site. But we have to do one quick thing first.

Part of the reference data for my site is in the key-value pairs in package.json for the gatsby-laurieontech project. I may or may not have forgotten to change this from the default, but now it's laurieontech. This snippet is truncated for readability.

{
  "name": "laurieontech",
  "description": "Laurie never changed the starter description, oops",
  "version": "1.0.0",
  "author": "Laurie Barth"
}
Enter fullscreen mode Exit fullscreen mode

This is important because it's how we're referencing the site project in the yarn workspace. So now we can add the theme to the site.

yarn workspace laurieontech add gatsby-theme-speaking-yaml@*
Enter fullscreen mode Exit fullscreen mode

It's written like this, with the @*, because the theme is unpublished.

To test out that this works, you can run this command again. You should see the theme listed inside the site information.

yarn workspaces info
Enter fullscreen mode Exit fullscreen mode

We also want to add the theme as a plugin to the gatsby-config.js file for our site, gatsby-laurieontech.

module.exports = {
  plugins: [
    'gatsby-theme-speaking-yaml',
    // other stuff goes here
  ],
}
Enter fullscreen mode Exit fullscreen mode

Install Dependencies into Theme

Now we want to start developing the theme itself. The first thing to do is figure out what dependencies the theme has. In our case, we're querying yaml and processing images. So we'll install those dependencies.

yarn workspace gatsby-theme-speaking-yaml add gatsby-source-filesystem gatsby-image gatsby-plugin-sharp gatsby-transformer-yaml gatsby-transformer-sharp
Enter fullscreen mode Exit fullscreen mode

Next, we want to create a gatsby-config.js file inside our theme. This is where we'll add the plugins that we just installed.

module.exports = {
  plugins: [
    `gatsby-transformer-yaml`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/src/data/`,
      },
    },
  ],
}
Enter fullscreen mode Exit fullscreen mode

Note that gatsby-image needed to be installed but not included, it's a utility

Create Theme

Now it's time to actually create our theme! Since we're building our theme off of an existing site, we can pull whatever code we want out of my site and place it into the theme project.

In this case, that's a section inside my speaking.js page. So we'll create src/component/speaking.js and move the relevant JSX over.

The existing code uses a page query and the theme is treating this section as a component, so it needs to use a static query instead. We'll make the change like so.

import React from 'react'
import { graphql, useStaticQuery } from 'gatsby'
import Img from 'gatsby-image'
import Event from './event'

const SpeakingSection = () => {
  const data = useStaticQuery(graphql`
    {
      allSpeakingYaml(sort: { fields: [index], order: DESC }) {
        edges {
          node {
            conference
            year
            url
            date
            location
            image {
              childImageSharp {
                fluid {
                  ...GatsbyImageSharpFluid
                }
              }
            }
            talks {
              title
              video
              type
            }
          }
        }
      }
    }
  `)
  return (
    <section id="speaking" className="wrapper style4 container">
      <div className="container">
        <h2>Appearances</h2>
        <div className="wrapper" id="speakwrap">
          {data.allSpeakingYaml.edges.map(({ node }) => (
            <Event event={node} />
          ))}
        </div>
      </div>
    </section>
  )
}

export default SpeakingSection
Enter fullscreen mode Exit fullscreen mode

Make sure data is usable

The code that is now being pulled from my theme is using data that lives inside my original project, NOT inside the theme. So I assumed that needed to move over to, but it actually doesn't!

This is where Laurie realizes that the theme doesn't need to hold the data, and when everything is compiled together it will be able to see all my yaml stuff!

However, in order to make sure that it works we need to check the gatsby-config.js for the theme to make sure it's using the correct relative path. In my case, that means minor changes to the gatsby-source-filesystem plugin configuration.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `src/data/`,
      },
    },
  ],
}
Enter fullscreen mode Exit fullscreen mode

Export theme component

The guts of our theme exist in src/components/speaking.js but our package.json is referencing an index.js file with only a comment in it. So we need to make sure that file is exporting our theme content.

export { default as SpeakingEvents } from './src/components/speaking'
Enter fullscreen mode Exit fullscreen mode

As it turns out, we can import and export at the same time! I really should add this trick to this post.

laurieontech image

Exports and Imports and Defaults, Oh My!

Laurie ・ Apr 29 '19 ・ 3 min read

#javascript #react #webdev #beginners

Use theme!

Now we can use our theme as if it were just another component in our Gatsby site.

In this case, that means changing my site's speaking page and importing the component from my theme to replace existing code. Note that the import is absolute because it's equivalent to pulling in an export from another project!

import React from 'react'
import Layout from '../components/layout'
import Hero from '../components/Hero'
import { SpeakingEvents } from 'gatsby-theme-speaking-yaml'

const SpeakingPage = ({ data }) => {
  return (
    <Layout>
      <Hero /> // this is a local component! I can use all this interchangeably
      <SpeakingEvents />
    </Layout>
  )
}

export default SpeakingPage
Enter fullscreen mode Exit fullscreen mode

Run Your Site with the Theme!

Now it's time to run our project with our theme.

Remember, that instead of the site's directory name, we're actually using the name we specified in the package.json, like so.

yarn workspace laurieontech develop
Enter fullscreen mode Exit fullscreen mode

And that's it! Now we can add to the theme, publish it, whatever we want.

Other Stuff we Discussed

This was quite the live stream, so naturally other things came up. Important topics such as:

  • Jason's relative height to other Gatsby employees

  • My terribleness with time zones

  • Terminal...and commands Laurie almost bricked her computer with

Oh, you meant related to our actual goal?

We did some refactoring of my app, talked about gatsby-image and a handful of other things.

At some point, I will write a post on a full refactor of my site.

But until then, I can't wait to see you all make the work you've done on your personal sites available as a theme for others to leverage.

We stand on the shoulders of the work that came before us!

Top comments (0)

Read next

prasetyomuhdwi profile image

Setup path aliases in React + Vite + TS Project πŸ€“

Muhammad_Dwi_Prasetyo -

cezar-plescan profile image

Level Up Your Angular Code: A Transformative User Profile Editor Project (Part 1)

Cezar PleΘ™can -

mike_andreuzza profile image

How to create a image gallery with Tailwind CSS and Alpinejs

Michael Andreuzza -

thejoernal profile image

How to reset an HTML form on submit using JavaScript

Joseph Ochego -