Gatsby Theme Authoring
Set up Yarn Workspaces for Gatsby Theme Development
Learn how to structure folders and configure Yarn workspaces to make the development of Gatsby themes easy.
In this lesson, we'll create two workspaces: gatsby-theme-events and site.
We will see how each workspace can be run separately as well as one depending on the other. In this case, gatsby-theme-events will be a dependency in our site project
For a written version of this course, check out the Gatsby docs.
Instructor: [00:01] In an empty directory, create a package.json. Inside the package.json, you're going to set private to true. Then you're going to set up your workspaces. This is an array of folder names. We're going to have two packages in this workspace. The first one is going to be called gatsby-theme-events. The second one will be called site.
[00:31] Next, we're going to create folders for our packages. The first one is going to be called gatsby-theme-events. It's going to need its own package.json. We'll also need site with a package.json.
[00:48] Inside the package.json, we're going to set up our theme. We need a name. This one is going to call it gatsby-theme-events. It's going to have a version. That version will be 1.00Then it's going to need a license. We'll set the license. Use the MIT license for now.
[01:12] Because this will be installed as a package, we have to provide a main file, which we'll mark as index.js. In order to resolve properly, that file does need to exist. For now, we're going to create an index.js. We just leave a little comment to let people know that it was left blank on purpose.
[01:34] In the site package.json, we're going to set it to private because we're not actually going to publish this site as an npm package. We're also going to give it a name, which is going to be site. This is what we refer to when we use a workspace.
[01:48] Next, we're going to set a version. That version will again be 1.00Then we will set a license. That license will be the MIT license. We're also going to want scripts here. For our scripts, we want to have a build script. This is going to run the gatsby build command. We want a develop script. This will run gatsby develop. Finally, a clean script. This runs gatsby clean.
[02:23] We want these to be available in both our theme and our site. We can copy-paste this over to our theme. Next, we can open up the terminal. We're going to install dependencies. To do this, instead of using the standard yarn add, we're going to use yarn workspace and then the package name, site, and add.
[02:50] We want Gatsby, React, and ReactDOM, as well as our theme. We're going to install gatsby-theme-events. The reason that we use the @* is because we want the workspace to pick up an unpublished theme.
[03:14] Now that the installation is complete, we can see that it is referencing gatsby-theme-events. If we run yarn workspaces info, we can see that the site is using the gatsby-theme-events from the workspace.
[03:33] Our theme needs to have Gatsby, React, and ReactDOM added as peer dependencies. We'll do yarn workspace gatsby-theme-events. Add with the -P to mark it as a peer dependency. React, ReactDOM, and Gatsby.
[04:01] During development, we're going to use our theme as a regular Gatsby site. We'll also set it up as a development dependency using -D. Once these finish installing, we can check our package.json and see that we have Gatsby, React, and ReactROM set up as both peer dependencies and dev dependencies.
[04:27] To make sure that everything's working, we can just go ahead and start up Gatsby in development mode. We'll start with the site, yarn workspace site develop. This will start our Gatsby server in develop.
[04:42] We don't have any content here. It's going to be an empty site, but we can grab out localhost 8000. We can go out to our browser and paste this up. We can see that Gatsby's running. There's no pages yet. Again, it's just going to give us this 404, but we can see that it's working.
[04:59] Let's do the same thing with the theme, so gatsby-theme-events run develop. Now we can see here's localhost 8000 again. If we come back out and refresh the page, again we get that 404. Gatsby's running. It just needs some content.
In order for me to add the local
gatsby-theme-xxxdependency to mysiteworkspace, I needed to manually add the dependency to thedependenciesobject in mysite/package.jsonfile.
I am having the same issue. I can't seem to get by the local dependency.
UPDATE
This is what works for me:
`yarn workspace site add gatsby react react-dom`
Manually edit `site/package.json` adding dependencies:
`"gatsby-theme-xxx": "1.0.0",`
Then install:
`yarn workspace site add gatsby-theme-xxx@1.0.0`
@LANDR and @Chuck, I looked into this and it appears that zsh doesn't allow the * to be unquoted, so it would need to be:
yarn workspace site add "gatsby-theme-xxx@*"
Thanks Jason
I did hear you refer to that on the Twitch this afternoon. I experimented and it appears zsh supports variations of this as well. For instance:
gatsby-theme-xxx"@*"
Great, I use zsh Glad I read the comments before I started the course
Hi Jason, apologies for my out of scope question, but what font are you using in your editor? :o
Hi! I use Operator Mono. More details about my setup/gear: jason.af/uses
Awesome, thanks! :)
@LANDR and @Chuck, I looked into this and it appears that zsh doesn't allow the
*to be unquoted, so it would need to be:
yarn workspace site add "gatsby-theme-xxx@*"
Hey Jason! Thanks for the tutorial. Is there any chance you have a link to any documentation on the "@*"? Just have never seen it before and can't seem to find it in the npm/yarn docs :)
@Pala as far as I can tell, the * in the CLI is a special character that gets handled differently between Mac and Windows. The quotes explicitly escape it, which avoids the Windows issue. I don't know of any docs; this is one of those "I know because I hit this error and someone told me how to fix it" things.
Can you give a suggestion how to setup this with a theme in /packages? I ask, because I've did it like you suggest... directly in the root directory of the project. Now that I scope my theme, I didn't get the workspace to run anymore. It seems yarn has some issues with scoped packages. The suggestion I've found was to put it into /packages and then put only this in the main gatsby-config.js:
{
"private": true,
"workspaces": ["packages/*"]
}
Any suggestion is very welcome!
@samuel if you want to see an example of a monorepo with a site and a theme in it, my Learn With Jason site is set up that way: https://github.com/jlengstorf/learnwithjason.dev — I'd recommend using that as a reference to get set up
good luck!
I got it now. Thanks.
In order for me to add the local
gatsby-theme-xxxdependency to mysiteworkspace, I needed to manually add the dependency to thedependenciesobject in mysite/package.jsonfile. Otherwise I got the following error: