Creating New Gatsby Theme with Typescript, MDX, and Theme-UI

Gatsby Themes provide a powerful way to share an opinionated set of configurations across multiple Gatsby sites. The features built into your Gatsby Theme will be abstracted out of your site and packaged as a dependency, providing an efficient way to develop similar Gatsby sites.

In this tutorial, we’ll set up a development workspace to build and demo a simple theme. Our workspace will be equipped with Typescript, ESLint, and Husky, so we can quickly start developing with a team. Our theme will support MDX pages, an MDX blog, frontmatter, syntax highlighting in code blocks, responsive images, and a custom theme built with the Theme-UI spec.

Skip to the end

• View Demo Site →
• Build a Gatsby site using this theme →
• Build a Gatsby theme using this workspace →
• View source code →

As you follow this guide, I encourage you to periodically reference my source code and commit history.

Prerequisites

Although this guide is fairly thorough, it will help if you have some basic experience with Yarn workspaces, Gatsby, and Gatsby themes. If you don’t, I recommend skimming through these resources to get up to speed.

• What are Gatsby themes?
• Building themes
• Gatsby theme authoring (video course)

Most Gatsby themes leverage the concept of Shadowing in Gatsby and Theme-UI to make theme development more efficient. It may be worth reading up on these topics if you aren’t familiar.

1. Set up workspace

1.1 Clone a starter workspace repo

• gatsby-starter-theme-workspace

  is a very simple and minimal starter

• gatsby-theme-mdx

  is a good starter for MDX blog support (I used this one)

1.2 Make the repo your own

The

root

1. Should have the following files:

   README

   ,

   package.json

   , 

   .gitiginore

2. Should have the following folders: theme and demo. Feel free to rename these folders.
3. The root

   package.json

   should have workspaces for theme and demo folders.

The

theme

1. Should have its own

README

package.json

.gitignore

2. The main

index.js

3. Rename the contents of the theme

package.json

• You can name your theme whatever you want, but you should make sure it is scoped using your npm username if you plan on publishing it. (You should create an account now if you don’t have one).
• I’ll be using

  @shetharp/gatsby-theme-candor

  as the name of my theme. For the rest of the tutorial, you should replace

  @shetharp

  with your npm username and

  gatsby-theme-candor

  with your theme name.

The

demo

1. Should have its own

README

package.json

.gitignore

2. Rename the contents of the demo

package.json

• Make sure under the dependencies section, you have a dependency for your theme. The name of this dependency should match the name you set in the theme

  package.json

  .
• Because we have not published the theme yet as an npm package and will be developing it locally, set the version to

  *

  so that yarn knows to look for the package locally.
• The dependencies section should look something like this:

"dependencies": {   
  "gatsby": "^2.13.1",   
  "@shetharp/gatsby-theme-candor": "*",   
  "react": "^16.8.6",   
  "react-dom": "^16.8.6" 
},

3. Update the demo

gatsby-config.js

package.json

plugins: [{ resolve: '@shetharp/gatsby-theme-candor', options: {} }]

1.3 Make sure your setup is working

1. Install dependencies in your workspace

yarn

2. Run your demo site

yarn workspace demo develop

• This command tells yarn to run the develop script from the package.json in your demo workspace folder.

2. Set up Typescript, ESLint, and Husky

We’ll be adding a few dev dependencies and configurations to help enforce good code quality and catch errors, especially when working with a team. You can skip this section if the juice isn’t worth the squeeze.

2.1 Set up Typescript

Gatsby comes with native support for Typescript, but we need to add some configurations since we are working with Yarn workspaces.

1. Add Typescript as a dev dependency to your workspace

yarn add -W -D typescript

• The

  -W

  flag tells yarn to add the dependency to your workspace's root

  package.json

2. Create a

tsconfig.json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "jsx": "react",
    "lib": ["dom", "es2017"],
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "include": ["./demo/src/", "./theme/src/"],
  "exclude": ["node_modules", "demo/node_modules", "theme/node_modules"]
}

3. Add a

type-check

package.json

"scripts": {
  "type-check": "tsc --noEmit"
}

• If you run yarn

  type-check

  it should run the typescript compiler.

4. Add an example Typescript page in

demo/src/pages/example.tsx

import React from "react";
import { PageProps } from "gatsby";

export default function TypescriptExample(props: PageProps) {
  return (
    <>
      <h1>Path:</h1>
      Example page using typescript.
      <pre>{props.path}</pre>
    </>
  );
}

5. Test that it is working. Run

yarn workspace demo develop

• If you modify the file to cause a typescript error (e.g.

  <pre>{props.asdf}</pre>

  ), you may notice that it updates your website, but Gatsby doesn't necessarily catch the error and crash. But if you run

  yarn type-check

  , it should catch that error. In the rest of the set up, we'll automate type-checking into our workflow.

2.2 Set up ESLint

We'll use ESLint to enforce consistent code syntax and formatting. (Learn more: Using ESLint and Prettier in a TypeScript Project).

1. Add ESLint along with its plugins for Typescript, React, and Prettier as dev dependencies to your workspace root

yarn add -W -D eslint prettier eslint-config-prettier eslint-plugin-prettier eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser

2. Add an

.eslintignore

node_modules
**/node_modules/**
**/.cache/**
**/build/**
**/public/**

3. Add an

.eslintrc.js

module.exports = {
  env: {
    browser: true,
    node: true,
  },
  parser: "@typescript-eslint/parser", // Specifies the ESLint parser
  parserOptions: {
    ecmaVersion: 2020, // Allows for the parsing of modern ECMAScript features
    sourceType: "module", // Allows for the use of imports
    ecmaFeatures: {
      jsx: true, // Allows for the parsing of JSX
    },
  },
  settings: {
    react: {
      version: "detect", // Tells eslint-plugin-react to automatically detect the version of React to use
    },
  },
  extends: [
    "plugin:react/recommended", // Uses the recommended rules from @eslint-plugin-react
    "plugin:@typescript-eslint/recommended", // Uses the recommended rules from the @typescript-eslint/eslint-plugin
    "prettier/@typescript-eslint", // Uses eslint-config-prettier to disable ESLint rules from @typescript-eslint/eslint-plugin that would conflict with prettier
    "plugin:prettier/recommended", // Enables eslint-plugin-prettier and eslint-config-prettier. This will display prettier errors as ESLint errors. Make sure this is always the last configuration in the extends array.
  ],
  rules: {
    // Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
    "no-console": ["error", { allow: ["warn", "error"] }],
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-var-requires": "off",
    "react/prop-types": ["warn", { skipUndeclared: true }],
  },
};

4. Add a

.prettierrc.js

module.exports = {
  printWidth: 120,
  proseWrap: "preserve",
};

5. Add

lint

lint:fix

package.json

"scripts": {
  "lint": "eslint . --ext .ts,.tsx,.js,.jsx",
  "lint:fix": "yarn lint --fix",
  "type-check": "tsc --noEmit"
},

6. Run

yarn lint

yarn lint:fix

eslint-disable

2.3 Set up Husky

We'll use Husky to run the linter and type-checker before we commit and push code to git. These pre-commit and pre-push hooks will allow us to frequently catch syntax inconsistencies and type errors.

1. Add husky and lint-staged as dev dependencies

yarn add -W -D husky lint-staged

2. Add a

.huskyrc.js

module.exports = {
    "hooks": {
        "pre-commit": ["lint-staged"],
        "pre-push": ["yarn type-check"]
    }
}

3. Add a

.lintstagedrc

{
  "*.{js,jsx,ts,tsx}": ["yarn lint:fix"],
  "{*.{json,md,mdx,yml,yaml}}": ["prettier --write"]
}

Commit and push these changes in your repo to git. You should see Husky in action!

3. Style your theme

Most Gatsby themes use Theme UI for developing themeable websites.

1. Add it as a dependency to your theme workspace, if it doesn't already include it.

yarn workspace @shetharp/gatsby-theme-candor add gatsby-plugin-theme-ui

2. Add it as a plugin to your theme's

gatsby-config.js

module.exports = {
  plugins: [
    "gatsby-plugin-theme-ui",
  ]
}

3. To create your own theme, you'll need to leverage Shadowing in Gatsby to shadow the theme file from

gatsby-plugin-theme-ui

theme/src/gatsby-plugin-theme-ui/index.ts

4. You can build your theme from scratch if you're comfortable with Theme-UI, or you can base it off of a preset/existing theme. You can reference the

gatsby-theme-candor

5. Tip: If you're making lots of changes to your theme, you might want to consider creating a theme preview page to see all of your theme's styles and components in one place. You can reference the gatsby-theme-candor Theme Preview page or its source code.

4. Set up MDX for pages and posts

To support MDX in your theme, you will need to add the

gatsby-plugin-mdx

yarn workspace @shetharp/gatsby-theme-candor add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

Make sure to add it to your theme's gatsby-config.js file. You can learn more about the plugin options in the plugin's official documentation.

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        extensions: [".mdx", ".md"],
        defaultLayouts: {
          default: require.resolve("./src/templates/Page.tsx"),
        },
      },
    },
  ]
}

4.1 Set up Gatsby Source Filesystem

1. In order for us to support MDX frontmatter queries, responsive images, and a content directory for posts, we'll need to add the

gatsby-source-filesystem

yarn workspace @shetharp/gatsby-theme-candor add gatsby-source-filesystem

2. Next, we will add the plugin to our theme's gatsby-config.js file and configure it to source posts and images. (Gatsby will automatically source from

src/pages

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "posts",
        path: "src/posts",
      },
    },
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "images",
        path: "src/images",
      },
    },
  ]
}

3. Gatsby will throw an error if these paths don't exist in your set up. To avoid this, create folders for each of these paths (you can place empty files as placeholders within them) in your theme's workspace.

4. We also want to make sure consumers of our theme don't experience a Gatsby build error because one of our required paths doesn't exist for their set up. We can use the

onPreBootstrap

gatsby-node.js

const path = require("path");
const fs = require("fs");
const mkdirp = require("mkdirp");

exports.onPreBootstrap = ({ store, reporter }) => {
    const { program } = store.getState()

    const dirs = [
        path.join(program.directory, "src/pages"),
        path.join(program.directory, "src/posts"),
        path.join(program.directory, "src/images"),
    ]

    dirs.forEach(dir => {
        if (!fs.existsSync(dir)) {
            reporter.log(`creating the ${dir} directory`)
            mkdirp.sync(dir)
        }
    })
}

4.2 Set up Gatsby Sharp for images

We will use Gatsby Sharp to support responsive optimized images in our site.

1. Install the plugins in your theme workspace

yarn workspace @shetharp/gatsby-theme-candor add gatsby-plugin-sharp gatsby-transformer-sharp

2. Make sure to add these plugins to your theme's

gatsby-config.js

module.exports = {
  plugins: [
    "gatsby-plugin-sharp",
    "gatsby-transformer-sharp",
  ]
}

3. We also need to install the

gatsby-remark-images

yarn workspace @shetharp/gatsby-theme-candor add gatsby-remark-images

4. Make sure to add this to your theme's

gatsby-config.js

gatsby-plugin-mdx

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        extensions: [".mdx", ".md"],
        defaultLayouts: {
          default: require.resolve("./src/templates/Page.tsx"),
        },
        gatsbyRemarkPlugins: [
          resolve: "gatsby-remark-images",
          options: {
            maxWidth: 800,
          }
        ],
      },
    },
  ]
}

4.3 Set up MDX Frontmatter

We want our theme to support frontmatter queries, so first add some frontmatter to your

.mdx

---
title: Hello World! Catchy title from frontmatter!
author: Fina Mitai
date: 2020-07-30
featureImage: ./redwood.jpg
---

This is the markdown content. Lorem ipsum dolor sit **amet**. 

We will reference the frontmatter with

pageContext

At this point, your website should be rendering MDX pages in your demo site's

src/pages

5. Programmatically Creating Pages

Because we have blog posts (in the

src/posts

src/pages

1. Install the

gatsby-plugin-page-creator

yarn workspace @shetharp/gatsby-theme-candor add gatsby-plugin-page-creator

2. Add

gatsby-plugin-page-creator

gatsby-config.js

src/posts

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-page-creator",
      options: {
        path: "src/posts",
      },
    },
  ]
}

3. Update the

gatsby-plugin-mdx

gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        extensions: [".mdx", ".md"],
        defaultLayouts: {
          default: require.resolve("./src/templates/Page.tsx"),
          posts: require.resolve("./src/templates/Post.tsx"),
        },
        gatsbyRemarkPlugins: [
          resolve: "gatsby-remark-images",
          options: {
            maxWidth: 800,
          }
        ],
      },
    },
  ]
}

4. Create a template for Posts in your theme's

src/templates/Post.tsx

import React from "react";
import { graphql, useStaticQuery, PageProps } from "gatsby";
import Layout from "../components/Layout";
import { Badge, Text } from "theme-ui";

export type PostProps = PageProps & {
  pageContext: {
    frontmatter: { [k: string]: string };
  };
};

const Post: React.FC<PostProps> = (props) => {
  const { children } = props;
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
        }
      }
    }
  `);

  return (
    <Layout>
      <Badge variant="accent">
        <Text variant="mono">Post template</Text>
      </Badge>
      <Badge variant="highlight" marginLeft={1}>
        {data.site.siteMetadata.title}
      </Badge>
      <h1>{props.pageContext.frontmatter.title}</h1>
      <span>{props.pageContext.frontmatter.author}</span>
      {children}
    </Layout>
  );
};
export default Post;

5. Run

yarn workspace demo develop

.mdx

src/posts

6. Set up a Blog Index Page

To list out all the pages in your website, you'll want to create a blog index page. In this example, we'll name this page the Blog page. However, you can name this whatever you want, such as SiteIndex, SiteMap, etc.

1. Create a new file

src/pages/blog.tsx

2. Add the following to the file

import React from "react";
import { PageProps, Link, graphql } from "gatsby";
import { Layout } from "@shetharp/gatsby-theme-candor";
import { Styled } from "theme-ui";

const BlogIndex: React.FC<BlogIndexProps> = (props) => {
  const { data } = props;
  const { nodes: pages } = data.allSitePage;

  return (
    <Layout>
      <Styled.h1>Blog Index</Styled.h1>

      <Styled.ul>
        {pages.map(({ id, path, context: { frontmatter } }) => (
          <Styled.li key={id}>
            <Link to={path}>
              <code>{path}</code>
            </Link>
            {frontmatter?.title && ` -- ${frontmatter.title}`}
          </Styled.li>
        ))}
      </Styled.ul>
    </Layout>
  );
};
export default BlogIndex;

export const pageQuery = graphql`
  query AllPagesQuery {
    allSitePage {
      nodes {
        id
        path
        context {
          frontmatter {
            author
            date
            excerpt
            featureImage
            title
          }
        }
      }
    }
  }
`;

3. You can verify the graphql query works by trying it out in GraphiQL. Essentially, this query is getting all the pages in our site and providing their id, path, and frontmatter. In our BlogIndex component, we use the frontmatter to render the title of the page and the path to link to the page.

7. Deploy your demo to GitHub Pages

We are going to deploy our demo site using GitHub Pages to make it easy to view the demo site without having to pull down and build the repo.

For this example, we will be deploying the demo site to https://shetharp.github.io/gatsby-theme-candor/, where

shetharp

gatsby-theme-candor

If you've ever deployed a Gatsby site using GitHub Pages, these steps should look familiar.

1. Install

gh-pages

yarn workspace demo add -D gh-pages

2. Because the root url of our website will have its repo name in it, we need to define a prefix in the demo

gatsby-config.js

module.exports = {
  pathPrefix: "/gatsby-theme-candor",
}

3. Next, we add a script to our demo

package.json

{
  "scripts": {
    "deploy": "gatsby build --prefix-paths && gh-pages -d public"
  }
}

4. Make sure your latest changes are committed to git. Then, change directory into your demo workspace

cd demo

yarn deploy

5. Make sure you've configured your GitHub repo to source from the

gh-pages

8. Publish your theme to npm

We're getting ready to publish our theme! Before we proceed, consider cleaning up or updating your

README

package.json

gatsby-config

1. At the beginning of this walkthrough, when setting up your yarn workspace, you should have given your theme workspace a name in its

package.json

"name": "@shetharp/gatsby-theme-candor"

• This will help the Gatsby and npm community keep track of who published the theme and avoid name collisions.
• You will have to use your own namespace for this step.

2. Verify that you are logged into npm by running

npm whoami

• If you're not logged in, run

  npm login

  to enter your username, password, and email.

3. Change directories into your theme workspace

cd theme

4. Publish to npm!

npm publish --access-public

• You should be able to see your newly published package in your npm profile.

5. If you decide to publish new updates to your theme later on, you will need to update the version number in your theme

package.json

Conclusion

Congrats on setting up your Gatsby Theme! In this tutorial we made an effort to set up a robust repository for theme development with a team--so share it with others and start collaborating!

As you continue configuring your theme to meet your needs, I encourage you to view the

gatsby-theme-candor

• View Demo Site →
• Build a Gatsby site using this theme →
• Build a Gatsby theme using this workspace →
• View source code →

If you found this tutorial to be a useful starting point, feel free to build your next gatsby site or theme on top of

gatsby-theme-candor