Gatsby themes are a new way to share functionality across multiple Gatsby sites. Yarn workspaces are an excellent way to set up a project for theme development because they allow you to keep multiple packages in a single parent directory and link dependencies together. For Gatsby theme development, that means you can keep multiple themes and example sites together in a single project. In this post, we’ll walk through how to use Yarn workspaces to set up a development environment for creating custom themes.
Installation and directory structure
First, if you don’t have Yarn installed already, follow the directions here to install Yarn. Next, create a new directory for the entire project, where you’ll be adding your theme and an example site later.
Create two subdirectories in this folder: one for the theme itself and one for the example site.
Add a package.json to the root directory with these subdirectories in the workspaces field. Note that setting "private": true is required for Yarn workspaces.
Change to each subdirectory and run yarn init -y to create a package.json for each one.
Be sure the name field in your theme’s package.json matches the directory name exactly.
This is currently a limitation of Gatsby theme shadowing, not Yarn workspaces.
Your directory structure should now look like this:
From the root directory, run the following to install Gatsby’s dependencies for the example site.
The yarn workspace <package> command will run Yarn commands for a specific workspace without needing to switch directories.
Then add the following as peer dependencies to the theme. This will ensure that the end user of your theme can choose any compatible version of Gatsby.
Base theme setup
Add a gatsby-config.js file to the theme directory.
Change the main field in your theme’s package.json to point to the gatsby-config.js file.
Example site setup
Add the theme as a dependency to the example site. By specifying the version here, Yarn will install the local dependency that hasn’t been published to npm yet.
In the example site, create a gatsby-config.js file and add the theme.
Add a src/pages/ directory and add a Hello, world page.
Add Gatsby develop and build scripts to the example site’s package.json.
Test your example site out to make sure everything is working as expected.
Open your browser to http://localhost:8000 where you should see your Hello, world page.
Adding functionality to the theme
Currently, the theme does nothing. This is the minimal amount of code required to develop a theme with Yarn workspaces.
To demonstrate the theme in action, use gatsby-plugin-page-creator to add a page from the theme.
Make a src/pages directory in the theme and add a demo page.
Stop and restart the Gatsby development server to pick up the new page from the theme. The theme’s page should be visible at http://localhost:8000/theme-page.
That’s it! By now you should have a basic Yarn workspaces setup to develop Gatsby themes with. Be sure to look for more posts on developing Gatsby themes in the near future, and you can read more about themes here on the blog.