Setting Up Gatsby Theme Development

[00:00:00]
>> So let's do a quick recap of where we are on this site, right? So what we've done to date is we've made ourselves a website that will show us a list of books, show us a list of all authors, and let us see individual pages for those.

[00:00:15]
The way that we were able to create that was by customizing the way that Gatsby creates pages and the way that it pulls in data. So we are pulling in some JSON data, this could be data from anywhere, we could pull it in from third party API's, or whatever we needed.

[00:00:31]
And once we have that, we are defining some relationships between that data. And then we're creating data nodes for each one, which puts it into Gatsby's graph qL layer. Then using that data, or actually before we use the data, we get down to this create resolvers here, where we're able to extend the data with custom resolvers that give us new fields.

[00:00:54]
So we created a biolink, which gives us the ability to link out and see the place to purchase. And we also created a cover, which is a remote image. So we look up the book in the open library API. We then get a link to the book's cover image, and have Gatsby pull that in as a remote file node.

[00:01:16]
And by configuring Gatsby config with image plugins, we're able to get an optimized image for each book cover. So we got quite a ways here. But as you may have noticed, this is not the most visually appealing site, we've pretty much ignored the visuals of this site entirely.

[00:01:38]
And what I wanna do is just kind of dig into how we can make this more visually appealing, but in a way that if I wanted to build more sites like this in the future, I could reuse that content. And so to do that, we're gonna introduce what's known as Gatsby themes.

[00:01:57]
So under the hood, a Gatsby theme is almost a Gatsby plugin. You install it the same way, we're gonna put it into the plugins array just like we would any other plugin. But the difference is a Gatsby theme has a few special properties, one It can extend our Gatsby config.

[00:02:13]
So we can install our own plugins that way, and we'll show you how that works here in a minute. You can provide components that will wrap things which is what we're gonna do with this particular theme. You can provide shared styles, you can do a whole lot of Kind of foundational work that makes building multiple websites even easier if they're all kind of in the same vein.

[00:02:38]
So this is a really, really powerful approach if you are an agency developer. If you work with clients, and you want to have the ability for a lot of different websites to start with the same general boilerplate whether that is. If you're building a frontend that's a little more advanced, maybe you need to wrap everything in context providers.

[00:02:57]
Maybe you've got some shared hooks that you use in almost every site that make your life a little bit easier. Or maybe you're using tailwind, and you've got a base config. Any of those sorts of things can be wrapped up into a Gatsby theme, and then installed onto a site so that you start at that point without having to build your own starter that you can then maintain.

[00:03:16]
The benefit of this is that if I use a starter, I'm getting a copy of that site, and all of its config, and all of its components, and everything that's in it. And if I make changes, it's now completely diverged from the starter. If improvements get made to the starter, I have to manually port those into my code, which is to be honest, probably never gonna happen.

[00:03:39]
I've tried this a few times. Never in my history as a developer, unless I was under duress, have I voluntarily gone and gotten changes from upstream and lovingly ported them into my code. It's usually not possible because your code, it diverges too much. With a theme though, a theme is an NPM package, it's separate from your site.

[00:04:00]
So if a theme gets updated upstream, I can update the version of my theme. And assuming the authors didn't make any breaking changes, I just automatically get those improvements. It's just like using Gatsby or just like using any other NPM package. I do NPM install my theme at latest, and boom, I got the changes.

[00:04:17]
So this is a great way to keep things in sync. A really good example of this in practice is if you look at the Apollo Graph QL Docs, these are set up as themes. So if you look at the docs, they have all of these different tools. And so each of these has its doc's in a different place, and they're able to keep all of the common stuff.

[00:04:44]
The sidebar styling, the shared header, the search functionality, all that lives in shared repos. But if we go and actually edit this. We can see that this is the Apollo Docs. And then if I go to, let's go to React. And I go to edit the React Docs, this is in a different repo.

[00:05:06]
So each of these is its own kind of thing, they're separately maintained, but they all have this really unified feel. And that's because Trevor Blades, who's the developer who built this did a really great job of setting up a series of sharable Gatsby themes. So this is a really powerful approach that you can take and use in your code.

[00:05:27]
So let's start that, right? So the reason that we set up a mono repo is to make this as easy as possible to get started. So I'm gonna create two new files in a folder. So our theme, I want it to be called gatsby-theme-shared-nav. Now I could put this in a /packages folder or a /themes folder whatever, but no benefit in over nesting here, so I'm not gonna bother.

[00:05:50]
So I'm gonna create a Gatsby config, and I'm also gonna create a package.json. And so the Gatsby config, all we need to start is nothing, we're just gonna export an empty object. And the package JSON, we're gonna set a few basic details. We wanna know name, and we're gonna call it gatsby-theme-shared-nav.

[00:06:15]
Again, we're in a mono repo which means that whatever the folder name is, if this is what yarn workspaces are gonna use when we wanna start the theme or install the theme. So if these don't match, that can be kinda confusing. So I would just say, if you don't wanna call it gatsby-theme-shared-nav, that's fine.

[00:06:32]
But call the folder and the package the same thing, or you're gonna get real confused. Then we're gonna set a version. We're not gonna publish this today, so the version is more just to keep NPM from yelling at us, and then we're gonna set a main. And this is important, main will default to index.js, but the main field is what node, and NPM, and yarn use to determine whether a package is valid.

[00:06:59]
So if you put in index.js and there's no index.js in here, your theme will throw errors, it'll say it's incorrectly configured, or no main export, or something like that. So you can, and a common practice is create an index.js and just it's a no op, just put in a comment that's nothing to see here.

[00:07:20]
And that's fine because then your main can be index.js, or you can just change what this main field is. And the last thing we're gonna do is we're gonna set a license, and we'll call it MIT. And so the reason that we set these fields is to register this as a package and to prevent getting complaints.

[00:07:38]
Like we don't want a notice that our package is unlicensed or a notice that our version is invalid or something like that. Those can all cause problems and just generally they cause. So, now that we've done that, we can tell yarn to track this. So I'm gonna come in here, and I'm gonna say, gatsby-theme-shared-nav, cuz now I wanna track this folder.

[00:07:59]
And if I come out here, and I look at what's in our yarn workspaces, which you can do by doing yarn space info. It's gonna show me two workspaces, one is site. Okay, that makes sense. And then gatsby-theme-shared-nav, here's its location, and perfect, that's what we want. So now that I've got that, I'm going to add Gatsby to our theme.

[00:08:24]
So yarn workspace gatsby, whoops. gatsby-theme-shared-nav, and you wanna add this as a peer dependency, because we don't want two copies of Gatsby, but we do wanna make sure that Gatsby is installed when you use this theme. So peer dependency is a way to make that work, so the dash capital P is how we do that.

[00:08:45]
And again, we're using yarn workspace theme named add instead of like NMP install or yarn add, because we want to make sure that it shows up in this package JSON and not this package JSON. And that's how yarn workspaces handle that. Okay, so we've installed, and now we're gonna install the custom theme into our site.

[00:09:10]
So, how we do that is we get into our terminal, and we're going to say yarn workspace site add gatsby-theme-shared-nav. And to get it to pick up the local theme, we're gonna say @"*", and I'm using z shell which means I have to quote that star. So @"*" is how we're gonna do this, so I hit Enter.

[00:09:35]
And instead of adding the remote theme, it links our dependencies and gives us what we want. And then, I'm going to say, yarn workspaces info again. And now, you can see site and here workspace dependencies including the gatsby-theme-shared-nav. So this is what we wanted, this is what we were after.

[00:09:59]
We have a site that is now using the theme, and that theme is local for our development, which is gonna make our lives really easy. So if we can start this right now but honestly nothing will happen yet because it's an empty theme, it's just kind of there.

[00:10:21]
So let's not even bother cuz if I started it, it would just start, we wouldn't even see that we installed the theme, it would just be like, okay, your site started.