This course has been updated! We now recommend you take the Intermediate Gatsby, v2 course.
Transcript from the "Workspace Setup" Lesson
[00:00:00]
>> Jason Lengstorf: The starter has a few things in it so that we don't have to write all of the code from scratch, but for this first part, we're gonna be developing a theme. And to develop themes in Gatsby, we need something called yarn workspaces. So a yarn workspace is a way that we are able to work on two packages simultaneously.
[00:00:22] So typically speaking, if you're working on a site if you wanna use a package, you would yarn install the package name and it goes into your package JSON and and then you can work on it. But if you wanna make a change to that package, then you would have to publish it to NPM.
[00:00:38] And then reinstall it at latest to get those changes. And that's really cumbersome and we just don't wanna do that, right? So what yarn workspaces will let us do is it lets us hook up a local folder as a package. So once you've got yarn workspaces set up, we can set our theme as a package that we can yarn install.
[00:00:58] But it will do it in a way that if we make local modifications that will get picked up by the site that we're developing with. And that's important because Gatsby themes are designed to take configuration options. And that means that they don't run standalone. They have to be installed by another site in order to function properly.
[00:01:16] So, what we're gonna do first is we are going to create a folder for the theme. So I typically call this packages because it's something that wouldn't be done top level. You can call it whatever you want, there's not a hard and fast naming convention here. This is just what I picked up, you're welcome to do whatever you like.
[00:01:40] And then I'm gonna use the name of the package. So we'll do gatsby-theme-docs. And inside of this, I'm gonna open up my terminal and get into it. Let's go into packages, gatsby-theme-docs. And then I'm going to run yarn init. And what this will do is it's gonna ask us some questions.
[00:02:01] So the name yes, I wanted to be gatsby-themed-docs. And it's important to remember that because that is what we're gonna have to use. Like we will do yarn workspace and the name of the package. And an important note about Gatsby themes, the Gatsby theme at the beginning is important.
[00:02:16] You have to name your theme with Gatsby dash theme. That's part of how we work the shadowing algorithm. So when you're building a custom theme, you always need to use Gatsby theme. Then we can keep the version default we don't need a description. The index.js entry point is fine.
[00:02:34] We'll skip that use default, okay? So once we have that, when we look into our package Jason, we can see here that we've got the theme docs. And that's gonna be the name of our workspace. So to set up work spaces we're gonna go out to the theme route, and we're going to create a package.json.
[00:02:59] And this one's a little different from the average one. So first we're gonna set it to private because it has to be private in order for workspaces to function. You can't publish a workspace. Then we're gonna set up workspaces, which is an array. And we're gonna set this up to read from two folders.
[00:03:16] The first one is gonna be the packages folder because we wanna be able to use that theme that we just created. And the second one is the site's folder. So we've got a bunch of sites in here. So we're gonna say anything inside of sites, you should also read as a workspace.
[00:03:32] Once we're in here, then I can do yarn workspaces info. And what it'll show us is each of these sites shows up as a package. It’ll show us where it lives. Then, it’ll show us if we have any workspace dependencies. We can see here at the beginning, none of these sites have any workspace dependencies.
[00:03:53] Now, this one does, but we’re not gonna worry about that, because it’s not really relevant to what we’re doing today. And then we've got our gatsby-themed-docs, which is set up in here properly. So what we do need to figure out though, is one thing that's important to know about packages is that packages rely on this main folder to determine whether or not the package exists.
[00:04:17] So when you install a package if you try to use it, the first thing that node will do is it'll look into that name and make sure that whatever the file is exists, and if it doesn't, it'll say that the package is invalid. So we're not actually gonna use an index js.
[00:04:33] So we're just gonna create it and then make a little note so that people know that this is intended. It's kind of like this page intentionally left blank sort of thing. You can put whatever you want in there. I boop is like my standard silly comment.
>> Jason Lengstorf: Once this is set up, now we can set up the theme dev site.
[00:04:59] So we're just gonna create a whole new site inside of our site's folder, we'll call it theme-dev. And again, we're gonna pull up the terminal, go into the,
>> Jason Lengstorf: Sites/theme-dev and then we will yarn init again. And this time we'll keep the name theme-dev, keep the version, description, all that can stay the same.
[00:05:26] But what I'm gonna do is I'm gonna set the private on this one to true because typically speaking, you don't wanna publish a website as a package on npm net. You could, but there's not really a good reason to do that. So then in here, we're gonna have our package JSON and it's set to private so that we don't accidentally publish it.
[00:05:48] In this, I can now add a few things. In the end there's a small difference. Typically when you add packages in yarn or NPM, you do NPM install or yarn add. So with workspaces, we just prefix the ad with the name of the workspace we wanna use. So I'm gonna say yarn workspace theme-dev and then I'm gonna add.
[00:06:09] And now, I can just add whatever I want. So I'll do gatsby react and react-dom. And we'll just check out in here that this is gonna do what we want. So it's installing
>> Jason Lengstorf: Okay all right, so it showed up the way we expected. So now what we wanna do is we wanna install our theme.
[00:06:30] yarn workspace theme-dev add, and then to quote it out for Windows and SeaShell. We'll say gatsby-theme-docs @* and @* just means that node will be okay with the fact that it's not a published package.
>> Jason Lengstorf: So once we get that, we'll see it pop up in our package JSON.
[00:06:52] And here we go. So now if I run yarn workspaces info again. And this is where it should be portal. Then I can see if I look at our theme-dev, now we've got workspace dependencies in here. And what this means is that gatsby-theme-docs is being treated as a package it will work exactly the same as a package installed from NPM.
[00:07:14] But the benefit now is that it's using local file. So when I make changes to this gatsby-themed-docs folder up here in the top left, that will reflect in the theme-dev site as if it were downloaded from NPM. So, next we're going to get into our theme-dev and we're going to install this theme.
[00:07:38] So let's just go ahead and create a gatsby-config.js. This is gonna be kind of the heart of any standard Gatsby site. So let me drop this down a little bit and we'll say module.exports and that's going to be a config object. And inside of this we're gonna have a plug-ins array.
[00:08:05] And the way that you install a theme in Gatsby by default, if you wanna use all the default options and everything, is you can just drop it right in there. So we're gonna say gatsby-theme, if I can spell it, gatsby-theme-docs.
>> Jason Lengstorf: And upon saving this, we are now effectively using this theme.
[00:08:28]
>> Jason Lengstorf: And it won't do anything right now, but it won't explode if I start it. So I'm going to come in here, and I'm just gonna add some scripts so that we can start Gatsby from the command line. So let's add a scripts key. And we'll put in develop, and our develop command is gonna be gatsby develop.
[00:08:51]
>> Jason Lengstorf: So now, what I should be able to do, and this is an empty site, so it's just gonna give us a 404. But I can do yarn workspace theme-dev develop. And this should start our gatsby site
>> Jason Lengstorf: Okay, so we're up and running and we can see now that it exists so if I switch out to here.
[00:09:16] And run the page we can see that Gatsby is running, we don't have any content or anything in herebBut it's doing what we expect it is actually loading the page. So that puts us in a position that we wanna be in, which is that we can start actually developing on the site.
[00:09:31] So this is kind of the workspace is set up. That's that's where you for any theme-dev, this is where you're gonna wanna start basically
>> Jason Lengstorf: So let's go ahead and commit that. I'm gonna check out a new branch. So we'll do git check out branch. And we'll call this fernan masters progress.
[00:09:53] And I'm going to check git status,
>> Jason Lengstorf: Okay, and I'm just gonna add everything.
>> Jason Lengstorf: This shows is in our queue and we've got a pack of json which is for work spaces, then we've got our gatsby-theme-docs the packages on the index. The gatsby-config and the package.json for the theme dev site, and then a yarn.lock, which is just tracking dependencies.
[00:10:22] So I'm going to go ahead and commit that. And I'm gonna use conventional commits. So we'll say theme-dev,
>> Jason Lengstorf: Workspace setup.