Getting Started with Gatsby Themes

Shahrooz Me

Hi, I'm Shahrooz, a front-end developer. I'm the author of this blog, nice to meet you!

→ Follow me on Twitter!


Interesting word, huh?

It’s an interesting word because everybody defines what a theme is slightly differently. We’ve got WordPress where you’ve got child themes, and there is Drupal which also has a concept with themes and other products like Hugo also have a concept of themes. But the way you use them is typically very different.

At first I answered some questions that you might have about Gatsby themes and after that we will build a Gatsby theme from scratch.

What is a Gatsby theme?

Gatsby themes allow you to focus only on the parts of the site and app building process that you need to care about by abstracting the rest away into a package.

What is the different between themes and starters?

Gatsby themes kind of ultimately operates very similarly to a starter except that you can build it as a library. What this means is that you can easily publish it and others can install and use it without worrying about the implementations.

You hyped yeah?

Let’s create our very first Gatsby theme.

Getting Started

Create new directory

mkdir Gatsby-themes

Navigate to the directory

cd Gatsby-themes

Create a package.json file

yarn init

Tidy up your package.json file and create workspaces which includes the project name, site, and your packages. Both of these directories will include their own package.json files.

Now this is how your package.json should look like:

  "name": "gatsby-site",
  "version": "1.0.0",
  "private": true,
  "workspaces": ["site", "packages/*"]

Next you want to create your theme and site directory. Make sure the names that you choose for your directories are the same as what you put in your workspaces. Then you will want to yarn init the theme directory and the site directory.

mkdir site
mkdir packages
cd packages
mkdir theme
cd theme
yarn init
cd ../../site/
yarn init

After using yarn init you will be asked a few questions. The main thing you will want to pay attention to is the entry point. For the theme directory, you can leave the entry point as index.js (just make sure you have an index.js file) but for the site directory, you should point gatsby-config.js. Next, you will want do yarn workspace site add gatsby.

Gatsby should now be added to your site directory if you look in your package.json file. Also you need some adjustments which is adding “scripts” and the name of your Gatsby theme, in this case, theme to your dependencies. Also you will want to add react and react-dom.

This is how your package.json should look like:

  "name": "site",
  "version": "1.0.0",
  "main": "gatsby-config.js",
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build"
  "dependencies": {
    "gatsby": "^2.1.33",
    "react": "^16.8.4",
    "react-dom": "^16.8.4",
    "theme": "*"

Now it’s time for theme but before that let’s setup some little things.

Installing MDX and gatsby-plugin-page-creator

What is MDX?

MDX is markdown for the component era. It lets you write JSX embedded inside markdown. That’s a great combination because it allows you to use markdown’s often terse syntax (such as # heading) for the little things and JSX for more advanced components.

Read more about Gatsby+MDX here.

In your theme directory, add src/pages/index.mdx

Then you need to add gatsby-mdx and MDX as dependencies. yarn workspace theme add gatsby-mdx @mdx-js/mdx @mdx-js/tag

Next, you will want to add gatsby-plugin-page-creator yarn workspace theme add gatsby-plugin-page-creator

Gatsby plugin that automatically creates pages from React components in specified directories. Gatsby includes this plugin automatically in all sites for creating pages from components in src/pages.

In the future, Gatsby will automatically handle adding the page-creator plugin.

Next, you will want to create your gatsby-config.js file under your theme directory.

module.exports = {
  plugins: [
      resolve: `gatsby-mdx`,
      options: {
        defaultLayouts: {
          default: require.resolve("./src/components/layout.js"),
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`,

Now, you can make sure site is linked to theme.

yarn workspaces info

Your workspace info should look similar to this:

  "site": {
    "location": "site",
    "workspaceDependencies": ["theme"],
    "mismatchedWorkspaceDependencies": []
  "theme": {
    "location": "packages/theme",
    "workspaceDependencies": [],
    "mismatchedWorkspaceDependencies": []

Lastly, you’re going to want to add a gatsby-config.js file to your site directory.

module.exports = {
  __experimentalThemes: ["theme"],

While you’re still in the site directory, you are going to create an index.mdx file in the pages folder.


Your website content goes in index.mdx

Styling Layout and Components

Next, you will navigate to the theme directory. You will then create a components folder under src, and in components you create a layout.js file.


Inside of your layout.js file, you can add your styling.

export default ({ children }) => (
      maxWidth: "650px",
      margin: "50px auto",

Using Your Theme

It’s finally time to use and share your theme! You can push your whole directory (gatsby-themes) to GitHub.

If you want to check your progress, go to the site directory and

gatsby develop

If you ever want to use your theme, you will do:

gatsby new name-of-project theme-url

Troubleshooting Plugin Errors

If you run into an error that your theme plugin can’t be found, try clearing your cache. You can either use rm -rf .cache in your terminal, or you can add:

  "scripts": {
    "clean": "gatsby clean"

to your package.json file. Then you can use npm run clean in your terminal.