The Gatsby team recommends developing themes with Yarn & Yarn workspaces which can be intimidating to users who are not yet familiar with workspaces. If you're one of these people or never heard of Gatsby themes before I'd highly recommend visiting the official documentation on Gatsby or watching Jason Lengstorf's "Authoring Gatsby Themes" egghead.io course. After going through that you might ask yourself how you could set up TypeScript or even ESLint & Cypress — this blogpost will explain to you how to exactly do that!

If you're looking for a guide on how to set up ESLint & Cypress with Gatsby themes and Yarn workspaces this article should work for you, too, if you skip the TypeScript portion and install other ESLint packages. Please leave a comment or contact me if you need help.

At the end of this tutorial you should have a Yarn workspace with ESLint linting + Cypress tests + TypeScript for both the example and theme. You can write your theme with TypeScript and have the same ESLint config everywhere. And if you wonder how people could use your theme if they don't use TypeScript: That's no problem at all! Gatsby's shadowing works with other filenames if you import modules without the filename extension (so people can shadow the file about.tsx with about.js or about.jsx ).

As mentioned above you should have some sort of understanding how Gatsby themes work and probably already used them a little bit before going through this tutorial. I assume that you have all necessary dependencies (e.g. Yarn) installed to run workspaces and Gatsby in general.

To not bore you with writing a boilerplate you'll use the "Gatsby theme workspace starter" to have a starting point. Clone this repository, go into the newly created directory and run yarn to install the dependencies. If you're stuck in between the steps of this tutorial or want to look at some code I encourage you to visit my fork of the aforementioned repository and skim through the commits (or have a look at the tutorial branch). You can also watch Amberley Romo's egghead.io video to see the setup.

Let's get started!

At the time of writing this tutorial Gatsby doesn't have first-class TypeScript integration and most people use gatsby-plugin-typescript which uses Babel under the hood. In this article you'll only use this plugin, if you want to add type checking you should check out gatsby-plugin-typescript-checker. The former plugin allows you to write .ts/.tsx files (but not for gatsby-config, gatsby-node etc.).

Install the typescript plugin to your theme:

yarn workspace gatsby-theme-minimal add gatsby-plugin-typescript

Add the plugin to your theme's gatsby-config.js