Creating a Gatsby Theme with John Otander

Joel Hooks: [00:00] it's talent. This is John Otander. He's a developer extraordinary and a friend of our very own, Taylor. That's where I met John at, anyway. As it happens, we have a lot of crossover interests and associations. Now, he's on the Gatsby core team, fixing it, to make the content web wicked.

John Otander: [00:26] Finally. At least we'll see.

Joel: [00:28] Yeah, man. We'll see how it goes. Will WordPress run supreme?

John: [00:33] No if I have anything to say about it.

Joel: [00:37] I just want to get into it, honestly. We don't really have to do a bunch of formal stuff. This is just a casual get together to look at Gatsby theming. I've read a little bit. I've talked to a Chris Biscardi about it briefly. I've followed along with what Gatsby's doing.

[00:58] My general take...and I wanted to tell you how I look at Gatsby themes, and then you can tell me how off the market I might be. I look at Gatsby themes as a way to separate configuration, to where we have repeatable configuration, and maybe design and other stuff, but mostly the configuration.

[01:18] I want to use the same setup across multiple sites and share it, and let other people use it, but then also allow them to customize and do their own design work, and build their Gatsby site to their needs, but saving them the hustle, the groundwork of the core configuration. Is that the...?

John: [01:40] Yeah. Pretty much. You have it right about perfect. I think the one thing I would also add is that with three theming, they can be like an app unit. You can have particular collections of concerns. You can have a theme for Gatsby theme blog, and then also Gatsby theme e-commerce.

[02:02] When you're as an end user, if you're starting out with just a blog, you only need to install that one theme to get running, writing some markdown. As soon as you decided that, "Oh, yeah. I'm going to add a store," you just add in that next theme and you just compose them together.

[02:18] You can make themes as modular or monolithic as you'd like. I would be really interested to see how the community runs with it, because you can decide how you want some architecture themes, and share them with the community, or internally as a company.

[02:35] I think that will be one of the very powerful use cases, is I'm an open source company, and we have a bunch of different projects that we want documentation for. You can create one theme and install it in each of these different repos. You just pointed at a docs directory or something, that it will construct the whole doc site for you.

Joel: [02:55] It's like meta plugins, almost?

John: [02:59] Pretty much. A lot of times people think it's only for scheming and aesthetic concerns, but really, a theme can be anything that a Gatsby site can do, which is pretty cool.

Joel: [03:13] It's funny because, in my head, I actually had it as the opposite. I was thinking more the data and the underlying functionality of the site, being able to package it in in a theme. Visually, it makes a lot of sense, too. You could do that, right? I'm stuck in functionality, but then I can also put a visual theme on top of that as well, and get a combination of these things.

John: [03:34] We've just recently introduced...I guess it's called trial beaming. That's now actually supported. It's still, of course, experimental. It allows you as a theme author to install other themes, and compose them together, and customize them, and then publish that as your own theme.

[03:51] It's a way where you can really powerfully remix things, but also be...if I'm a theme author, and I want to create six different blog themes, you can create your blog base that sets up all the data structures, and it creates pages, and then create 10 more themes that just inherits from that initial base.

[04:13] You can use it as building blocks to start with one layer of abstraction, and stack another thing on top, and go with it from there.

Joel: [04:21] That's cool. Where are the themes at, and the release cycle? Maybe Jason can since he's joined us. Are they ready to go? Is this something that's good to go in Gatsby as it sits today, or are we still in the development of themes, in the thick of it?

Jason: [04:41] Where themes are right now is the code is good, but there aren't a lot of docs. We're working on that now. There aren't a lot of examples. You'd be adventuring.

Joel: [04:58] We're adventuring today, but it's a guided adventure. That's the best kind.

Jason: [05:03] Yes.

Joel: [05:04] If we want to just jump into it, what we're going to do is we have a naked blog starter which I linked to in the chat. It's a good candidate to...honestly, it probably has multiple themes that we could pull out of it. Just in general, it's something that we're going to reuse and stamp multiple sites with this basic functionality. For us, that's newsletter sign-ups.

[05:31] It's a blog theme, so we have blog posts, we're using MDX, and all of this other core functionality. So far, we've used it to build three or four sites. The starter works just fine, but it feels like something that is perfectly suited for theming, or using as a theme overall.

[05:51] I posted it on Twitter, and John was like, "Oh, that should be a theme." Here we are, and John's going to generally show us how we could take this and make it into a Gatsby theme. Jason and I are here for color commentary.

[06:07] Then Ian's going to, if anybody has any questions in the chat, he's going to be your mouthpiece on the broadcast panel here. Does that sound good? Should we just jump into it, get to coding?

John: [06:22] Yeah, let's do it. Essentially, where we're starting right now is I've just clone the starter, as we had it all right here in the this directory. I guess the first step that we'll do here is to convert it, so we can use it as a Yarn workspace.

[06:40] That way, we'll be able to build our starter and also install the theme into the starter and use that as the development workflow. That way, we don't have to do things like Yarn linking or having to publish it to NPM to then install. It gives us this seamless workflow while we're just trying to hack this out really quickly.

Joel: [07:05] Does NPM have anything analogous to that, or is that the killer feature of Yarn at this point?

John: [07:11] For me, it's the killer feature of Yarn. It's basically the only reason why I use it, is for the workspaces. It's really cool, especially if you're developing a handful of packages in tandem. You can link everything together and have your examples that pull them all in.

Joel: [07:29] For plugins or themes and this kind of thing, it works out really good.

John: [07:32] Yeah.

Joel: [07:33] I've never used those, either, so I get to learn that as well.

John: [07:39] Essentially, what I'm just going to do here is create this packages directory. We'll call this gatsby-theme-egghead-blog. Of course, you got to have the tack two. Then we'll just move all of this actual code straight into that directory.

[07:56] Then from here, we can pretend that this our package. Then to actually start the workspace, we can just quickly init a new package, and go ahead and modify that. I imagine I'll probably need to make this bigger, too.

[08:12] Here, we essentially, in order to create the workspaces, we just have to put in a workspaces key and tell Yarn where to look. Firstly, we'll tell it that every directory in packages is a standalone package. We'll also create a starter directory and use that as...that's our example.

[08:36] Every time when we specify gatsby-theme-egghead-blog as a dependency in starter, Yarn'll just link them all together. We can just make changes in the Gatsby theme, and it will just lag that reloading for us.

[08:52] We'll just also tell this that it's private, since we're not actually going to be trying to publish this. Then from here we'll also create our starter directory. This will be our example, where we install the theme, and eventually, all the content that we scaffold out will also live there.

[09:11] That's the idea, so that now, when we use things like starters, they're never going to go away in Gatsby with themes. The starters can actually just install its app code as a theme itself. We can update it when needed. Here, we'll just scaffold out another package.json for our starter.

Joel: [09:37] The way workspaces work, each of these is just a separate project. Each one has its own package. Each one is an independent, multi-package repository at that point.

John: [09:50] Exactly. Here, we'll just add our start script, of course. That's gatsby develop. We don't need this main, description, or anything like that. We'll also specify this v private as well. We don't necessarily need it today, but it's just the way so you don't accidentally publish things.

[10:14] Then from here, we just need to specify our dependencies. One of those, of course, is Gatsby, and then the other one will be the theme that we're going to build out. Here, we'll just say gatsby latest, because we just want to make sure that we pulled in the most recent releases, adding to themes every day and making them better. Then gatsby-theme-egghead-blog. This is what we're going to be creating.

[10:40] [crosstalk]

John: [10:41] Go ahead.

Joel: [10:43] When Yarn looks at that, just in terms of the workspace, it knows that and relates the two together?

John: [10:49] Yep. Yeah, it'll see, "Oh, I've specified this dependency," but it knows it's another package. It just does all the linking. Then, I guess, to finish, tying this all together, we just change the name to using a theme convention. Then also, specify as the theme.

[11:10] Then the one last little bit we have to add is actually to specify names. This is like a package. This will allow Gatsby to be able to resolve the package and know that it's good to go. We add all that in, and then we get to do the Yarn.

Joel: [11:28] The main is the config, because as I understand it, that's effectively what a theme is, is a layering of configs?

John: [11:35] Yeah, but this is really just, it's almost there for hand-waving. Gatsby is like, when it builds themes, it just merges them all together. Just this way, when Gatsby first tries to build the site, it makes sure that it can resolve all the packages.

[11:52] If you specify main to an existing file, node won't get mad for saying, "Oh, there's not a package there." Another convention that you often see, especially in plugins, is you can also just add an index.js file. That's essentially empty as a no-op. Either of those approaches, they both work.

Joel: [12:13] You just need to point it at something?

John: [12:14] Yeah.

Joel: [12:15] OK.

John: [12:16] Now, we're doing the Yarn install.

Joel: [12:20] This is a random question. Do Yarn and NPM work together, like if you have a package lock and the Yarn lock, do they care? Have you ran into any problems with that?

John: [12:30] I haven't run into problems, but they just ignore each other. They both pretend, at least as far as I can tell, that, "I don't care about the package lock."

Jason: [12:39] The problem that you run into with it is that if you've got a package lock, Yarn will ignore it. NPM ignores the Yarn lock. Depending on which build system your team is using, they'll have a different set of dependencies, because they'll be using different lock files.

Joel: [12:58] Probably stick to one as the...?

Jason: [13:00] If you're working on a team, you'd want everybody to use the same one.

Joel: [13:03] Since we have a killer feature in Yarn, it's probably Yarn.

Jason: [13:08] If you're working in the mono repo, where you would have the workspaces, then yeah, definitely, you would want to use Yarn, because it makes it much easier.

Joel: [13:14] When you run Yarn in the root, does it go and do it for everybody? It's like a subproject in a workspace?

John: [13:20] It'll walk every package, every workspace you specify. It'll go ahead and facilitate the Yarn install. Then once this happens and we're done, we can basically then run scripts from the root by just specifying which workspace we want to run from.

[13:38] We can say something like, yarn workspace starter start, and that will run the start script and the package.json of the starter workspace.

Joel: [13:48] I can't get the gigabit here. It still makes me sad.

Jason: [13:50] Like I said, the best thing that ever happened was when I moved into the place I'm in now, and I asked if I could get fiber Internet. They said yes, and all I had to do was drill a hole in the wall. I was like, "Well, hold on, wait. I can just drill a hole in my wall?" It's the first time I've ever bought anything instead of renting. It was like, "Wait, I can just do that?"

Joel: [14:12] What, you go buy a drill? Ready. [drill sounds] Done. I've asked them never to call me unless they're offering me faster Internet. They'll call me, because you want the phone, you want the TV? I want none of those things. Is this call about faster Internet?

[14:29] My account, I should be flagged to never call me unless you're offering me faster Internet. To which the answer will always be yes. I was asking about the fiber, and they were like, "What do you want this for?"

[14:41] They're like, "It's like $1,000 to set up," and this, that, and the other, to my house. I was like, "I mean, I want it for Netflix and chill. Does it matter? I want the fastest Internet."

[14:52] I went through 20 minutes, the end result was, "No, you can't actually have that at your house." I was like, "We could have started there, without the quiz about my Internet usage. It's none of your business why I want fast Internet." I assume that's so they don't leave money on the table by having some lucrative business opportunity slip by them.

John: [15:16] I guess we can get started with some of actual Gatsby config changes, since it's taking its time. One of the big distinctions that's a little bit different when it comes to developing a starter versus a theme is in the themes, you have to tell it to...

[15:35] You have to use a require.resolve call, instead of patch lane. Since it will be installed as a dependency, the node module, it will attempt to look for it in the relative directory. We have to make sure we specifically do that.

[15:51] Otherwise, once this Yarn install happens -- which it's not done yet -- if we were to attempt to run it right now with that many changes, when it tries to programmatically create the pages from the blog posts, it will actually blow up.

[16:07] Right now, it'll search for the templates in the starters directory. Right now, we have this, the path.resolves. The way we can actually change that from the theme author's perspective to ensure that it attempts to resolve it in the correct way, we can change the path.resolve to require.resolve.

[16:29] That ensures that it looks relative in the file system. For both these templates, we can just go ahead and change these to be require.resolve. Now, we'll actually add the relative file path there. When it actually searches to create the pages with the template components, it will, I guess, connect everything correctly.

Joel: [16:53] Is that some you do just normally? Could you have just used require.resolve in lieu of that, and avoid this entirely from the beginning?

John: [17:00] Yeah. I think one of the things we'll probably work on with the docs and update them with slight tweaks, so it'll work in the theme context, or a local project context. That way, you don't have to do this dance. Since this is built as a starter, and following the existing docs, we have to make these quick little changes.

Joel: [17:22] It makes sense.

John: [17:24] This is literally the longest Yarn install I've ever had in my entire life.

Jason: [17:28] You sounded insulted.

Joel: [17:31] 397 seconds.

John: [17:34] That's crazy. My computer is quite slow right now. Now, the changes we've essentially made now is we've just changed how we're looking for the templates. We can actually now yarn workspace starter start. When we do this, it's going to attempt to build the Gatsby theme. Actually, in this starter, I think I didn't add the Gatsby config yet. We can do that.

[18:00] Right now, this will actually blow up on us, because we haven't given Gatsby any configuration. We'll add our gatsby-config. This is probably one of the parts I'm most excited about with themes, is how nice and simple the actual gatsby-config is now.

[18:19] Since we're using a theme, all we have to do is just say, "Use this theme." Right now, it's namespaced under experimental themes, because we haven't gone totally stable yet. We don't really anticipate any breaking changes now. It's more about just improving documentation and that kind of stuff.

[18:37] The way to configure it to pull in a Gatsby theme is to tell it just the name of the package. This would be gatsby-theme-egghead-blog. Now, this is really all the configuration that you need to do. Then later, if you decide, "Oh, I want to add a couple of plugins," you just add those keys in there, and it'll all just work together.

[18:59] It's a pretty nice way to get up and running. If the theme gets updated, you publish a new version of that to NPM. All you have to do in the starter is just tell it the new version. Anyone that started from that starter, they just have to update their theme package. They can pull in all the new changes, like whether it's bug fixes or added features, anything like that.

Joel: [19:26] They get versioned through NPM, so you can lock it down, or you can track with the newest version, that sort of thing.

John: [19:34] Exactly. As we see, Gatsby couldn't find the config, so it's like, "There's nothing to do here." Now, we've just added it. What we'll expect now, since I've done this once or twice before now, that it'll blow up now on gatsby-config.

[19:54] That's in the theme itself, because we haven't also reset the actual path resolution for typography.js. What Typography.js does behind the scenes is it caches a bunch of the stuff that it's doing internally. You basically just have to slightly change the way it requires those files from the theme.

Joel: [20:15] Is that specific to typography.js?

John: [20:18] Yeah, just based off the way it does caching right now. It's something we'll hopefully be able to update to make it a more seamless theme experience. Right now, it's kind of a missing piece. Here, we'll just do the same thing, where we do require.resolve. This just ensures that it looks for the cache in the right spot.

[20:42] After all that ceremony, here's the typography.js explosion. What was happening there is it was trying to look for the cache in the wrong spot when it was initially built. We changed the require.resolve there. Now, when we do the Yarn workspace, we basically rebuild everything. It will, I guess, be able to resolve the things.

Joel: [21:04] Is this actually starting like the original starter project? Is that's what getting built here?

John: [21:08] Yeah, we're building the starter project, which is then linked to the theme project code.

Joel: [21:16] Do we name it? It's in packages, right? You just migrated the entirety of that over to the packages Gatsby theme blog. Then the starter folder is empty, but it's all building into the starter folder. How is that functioning?

John: [21:33] Since we have the name starter, that's the name that then Yarn decides is the Yarn workspace. Any script you wanted to run here, like if you added a test script, it's basically just yarn workspace starter test, and it will run that script.

[21:54] Now, it's building the images. I guess we can start getting started with the content now, since obviously, the content lives in the theme directory itself. The way we'll want to change that is to move it into the starter.

[22:08] That way, when you scaffold out your app, you see the content, and you can just start writing from there. That's the cool part, too. The stuff that you want to live in the starter, like the content, can. Then all your application code is living off node modules and your Gatsby theme.

Joel: [22:28] Really nice separation of concerns at the end of the day.

John: [22:31] Yeah, because a lot of times, with the starters, you're intended to, here's the default content of your project. Then like right now, we bring in all of the application code, too, which is something you typically want to hide underneath the covers.

[22:48] Then down the road, we can add in developer tooling, so you can actually decide, "Oh, I want to eject from a theme," and then you can opt into pulling it in that code, if you don't want an upgrade path and that good stuff. That's the thought.

Joel: [23:07] Kind of like create-react-app -- not totally, but in a way -- it's similar, it feels like.

John: [23:18] Now, we actually have the page built, which is cool. As we'll see, all of that content is currently being sourced directly from the theme itself. We just want to move that over. I think the first thing we'll go ahead and start with is to actually move, or properly source, the pages.

[23:39] Right now, Gatsby will only look for pages in its relative, I guess, source pages. Right now, it's trying to build pages from the starter. If we create an index.js in the source pages here, then it would find it, and there wouldn't be a 404.

[23:57] Since by default, it would probably make sense for this theme to actually build out the index page and everything, we can use Gatsby as a plugin to the page creator. We can point it to the theme source pages as well.

[24:11] Until an end user creates their own index page, we'll actually instead render a page for them. That will be the theme page that we see, at least when you initially run the starter. We just have to add this gatsby-plugin-page-creator into our project.

[24:33] Instead of running this in your starter workspace, we're actually going to make sure this is installed in the theme. We're going to Yarn workspace gatsby-theme-egghead-blog add, our page creator. As this installs, we can actually then go into the gatsby-config and tell it to source pages from that page directory that we have.

[24:57] We can actually just cut and paste some of this configuration we have here. Right now, what this does is, the page creator, you can tell it a directory to look into, and it knows to create pages and infer the URLs based off of whatever's in that directory. We just tell it to look in the theme source pages. We just add a new path to it.

Joel: [25:20] You can effectively make as many page directories as you want or feel like having?

John: [25:25] Yeah, and that's a lot of times what large, big, complex apps will do. They can group their pages based off of different concerns. This will allow you to do the same thing. We'll make sure that we tell it to look relative to the theme itself, and just go to content blog. Also, of course, we have to add actually, require a path, so that...

Joel: [25:55] Is this replacing the source file system?

John: [25:59] It's replacing it. Well, it's not replacing it. It's additive to it. What it's doing is creating index and subscribe pages that are there until...Of course, if you add it to the starter, it will override it. Gatsby will see, the user will see, or the child theme has that page defined. That's the one that it'll choose.

Joel: [26:22] You pointed it at content blog, though, versus...I thought we would point it at source pages. Is that not the...?

John: [26:28] Oh, yes. You are right.

Joel: [26:31] Oh, OK.

John: [26:32] Source pages. Good catch. That might have been a moment, "I'm so confused. Why isn't this working?" I told it took in the wrong place. Now, we're actually sourcing those pages. We can restart the worker space.

[26:47] Normally, once you have everything set up in your config, it's a lot more seamless when you're developing you're theme. It's just when you have to resolve the paths, like the initial setups, like a couple...

Joel: [26:58] It's Gatsby in general. When you're building your config, it's a lot of stopping and starting. Then once you have that all built, and you're working on content, then it's nice and hot reloading.

John: [27:11] Yep. It's much faster and super quick. Once this builds, then we'll actually see the nice little splash page and everything that the starter creates. I guess while we're building this, we can start moving the content files over, too.

[27:31] We can just grab all these. That's the config. We'll want to bring over the content directory, so it lives in the starter itself. The one little change that we'll have to make is just to tell Gatsby source file system to look...

[27:50] We can get rid of this directory name that's here and just say content blog. By default, it will just search where Gatsby's running. We can actually clean that up and make it simple, because...What's going on here? Oh, I moved it over while it was still being installed. That's a bad idea.

Joel: [28:11] Oh, yeah. It hated you.

John: [28:13] Here now, we'll have the content that will be sourced from the starter directory, where our concerns are now separated in the way that we would like them to be.

Joel: [28:26] Your starter ends up being super light. It could be a place where somebody that is just concerned about content entirely would go and could work in that. I guess it builds up, though, right? We'd add to that over time. A lot of the times in the theme migrate over there, just depending on where it would best fit.

Jason: [28:45] You don't have to. The thing that's really cool about themes is that this gives you the opportunity that you could create a Gatsby site that was a gatsby-config and a folder called docs that's just markdown files. It's a really, really powerful model in that way.

Joel: [29:03] I love that, because it's super simple. The setup is easy. They don't have to worry about it. We could basically have sites up lickety-split, and just worry about content for them.

John: [29:13] It's a much gentler introduction to Gatsby for those that aren't familiar with React potentially, even, or GraphQL. It's a nicer abstraction if you don't want to see the knobs and dials. Some people love the knobs and dials.

[29:30] Then underneath the theme, you can peel back that layer. Then whenever you have some bespoke thing that you want to build out, like I want to create a different tags page, then you can start writing some GraphQL, make these customizations, and add some new components to do all that stuff.

Joel: [29:47] It's like opting into complexity, in a way.

John: [29:49] Mm-hmm, yep. Actually, now, we're all built. This is essentially like a working theme now. It's actually sourcing all the content from the starter, but all the configuration and stuff is still handled, like the MDX parsing, rendering, and all the themes and components are all actually in the Gatsby theme big head block. It's now essentially, by all purposes, it's a functioning Gatsby theme.

Joel: [30:20] Can I say that my placeholder makes me laugh pretty much every time I see it?

John: [30:25] Yeah.

Joel: [30:27] Anyway, that's amazing, though, actually. There's a lot to the setup. It's pretty complex, Yarn workspaces, all that stuff. Once that's done, now it's like a folder with our content in it, a super simple config, and we're off to the races.

[30:47] We could just start adding content to this or dig into it. The next step, I guess, to me would be to start breaking this down into thinking about the visual theme versus the data theme, for lack of a better word. I don't know if y'all are calling them anything in particular.

[31:04] Would that be the way you think about this, or how are y'all looking at, how do you divide this up further?

John: [31:14] A lot of times, I guess, the way we've been thinking about it -- of course, this is still experimental, and trying to figure out what the best practices are -- ideally, you have a couple of layers, where one is setting up your data model.

[31:30] Basically, just saying, "This is the shape of the content, and this is where I might source it from." Then you have the blog base that creates pages, handles tagging. Then you can have another theme that sits on top that's like, they don't even necessarily, that theme doesn't need to care about writing GraphQL.

[31:50] It just has presentational components, essentially. You would be like, "I'd create my header, and I'm just passing ops for the links, the title, and that kind of stuff." That's also something that you can define its best, whatever context, or what makes sense for your use case.

[32:10] It could be super monolithic, or it can have one that's presentational and one that sets up the data. That's where we've been leaning to the most so far, is to have a theme that only cares about presentational components, and just accepting props, styling, and CSS, and handling that.

[32:32] Whereas underneath the covers, you can have your base theme that does everything that data cares about, like creating the pages and everything like that.

Joel: [32:44] The plugins right now, you have a source plugin. That's a naming convention for source plugin. Would you have a source theme, then? Would you have a WordPress theme, basically, that you could put in that would be the base configuration for a standard WordPress site, Contentful, or however you might grab your data?

John: [33:01] Some of the next steps, and we're working on this now, is to have this way to model your data. This way, you'll be able to connect any type of data source to your same blog. That's coming. At this point in time, you have your base theme.

[33:24] If you have the same conventions of once you source your data, create them in the same way, and always render the post, you can have two different themes with different data sources, with a child theme that sits in front of it that handles things like themes, the scan, the CSS, and presentation of it.

Joel: [33:45] It depends on how much, because sometimes, granularity can just bite you, too. It can get too granular. You have to figure out the appropriate level for whatever your goals are at that point.

John: [33:57] I'm definitely a person where I like to copypasta a few times before I start to figure out what the next abstraction is, and that type of stuff.

Joel: [34:05] I think that's a very pragmatic approach. Somebody had a question about MDX, actually. The question is, can you use MDX with Contentful or some other CMS provider? I'm pretty sure the answer's yes, right? It's just text until it's processed. Is that a correct answer?

John: [34:26] Yeah, it's just text. The one part that will need to be improved is, there's no way to easily live preview MDX that is sourced from another place. Now, there's a prototype that I think Chris and one of the people from Contentful actually built as a little browser extension.

[34:47] That will live render using CodeSandbox, like the MDX that you write. Essentially, if you're just writing your component directly into the text of your Contentful, you can then, the way Gatsby MDX, it doesn't really care. It's just a string. You can form your queries, connect to that data source, and then just render it on the fly. MDX, all it really cares about is it's that string that you have.

Joel: [35:18] Once it gets into your system and the components, if you're referencing them, they are there, then it just works otherwise they just appear text, I would think.

John: [35:28] Yeah. We've actually used that with some prototypes with Contentful, where I just write in video and the actual YouTube embed code. It looks funny in Contentful, but as soon as it hits, its rendered to the page, of course, it will render the video embed.

Joel: [35:48] Where are we at with this in terms of this theme? Is this basically ready to rock as far as that goes?

John: [35:58] Yeah, it's ready to rock, but the next step we have to get into is, I guess, a bit more complex. My machine's being slow. One of the big pieces that I've noticed in the starter right now is we need to bring out a lot of the static queries, is the way that the starter currently works.

[36:21] The use case of a starter's a little different than a theme author. As a theme, you want to be able to pass in your config. It can use the Gatsby static query, so you can pass in things like...we can actually look at it really quick.

[36:37] Here in the gatsby-theme-egghead-blog, we have this theme, and we have this website. When we actually turn this into a full-fledged, functioning library, we would want to pull a bunch of this stuff out and pass it in as metadata.

[36:55] That way, we're reusing it. Like in the header, you can use the static query feature that Gatsby provides to use that to structure your content. That's what we would be one of the last steps to really make this a truly functioning theme.

[37:10] Then it's matters about how you want to break it up, or whether you want a blog base, and then a theme that sits on top, or all of that kind of stuff. Using static files for your configuration doesn't typically quite work from a theme context.

[37:26] You have to pass things like options or use component shadowing. Actually, that's one of the parts we haven't gotten into yet, too, where we can show really quickly.

Joel: [37:37] Let's see that.

John: [37:38] You can use component shadowing to override a component. For example here, let's just say we want to change the header. Using themes in Gatsby, you can use this feature called component shadowing.

[37:53] The way you do that is you can actually create a particular file. In this case, you namespace everything under gatsby-theme-egghead-blog. Any component that you define, when we actually build the site, will first look in the users directory before going into the theme.

[38:13] It's a way where you can tap into and customize rendering, which is really powerful for when you have this one-off thing, or we want the My Blog to have more padding, and be black-on-white instead. You can just override that header to do so.

[38:32] The way to do that is, like right now, we're also building some developer tooling around this, too. You can through the CLI, or in your development mode, explore the components that you can shadow. For now, you just have to look really quick at the theme source code.

[38:50] Here, we see there's a components directory with that header file. In our starter, if we want to customize that, we can basically create a new file that Gatsby will decide to search for instead. We have source gatsby-theme-egghead-blog.

[39:11] This is basically the way. Everything you put in gatsby-theme-egghead-blog directory will be first looked at, and if it's not found, will then go to the theme, if that makes sense. It's like [inaudible] . You can override whatever you want.

[39:32] Anything that's in the theme or the source directory of the theme can be overridden by the user, so that they can change theme tokens or design tokens. They can override the header or even override templates. Here, we'll create this header.js in gatsby-theme-egghead-blog.

Joel: [39:54] You can put the templates folder in there, or any of the other folders, basically. If it's a component, it's going to go in there and look there first, then drill down into the theme.

John: [40:05] Exactly. Here, we can just add in an h1. Then we'll have to do one more, I guess, build with my slow machine.

Joel: [40:19] Is that preemptive, where you know it's not going to work without killing that cache?

John: [40:24] There's a little bug in the component shadowing, where if we're over-aggressively shadowing right now, or when you add in a new component, you'll have to basically remove the cache before it knows to look there. That's something that, of course, before we get on stable, we'll be...

Joel: [40:42] I heard caching's hard.

John: [40:46] It's weird. It's like this one problem.

Joel: [40:50] One day, the robots will solve it for us. That's what I'm holding out for, anyway. I just don't mess with caching. I'm waiting for the robots to catch up.

John: [40:59] One of the interesting things, too, to consider now as you're offering themes is how to separate your queries and the data from your components a lot of the time. We've been experimenting with a way where we use static queries that wrap the presentational components.

[41:17] That way, you can query the site and metadata to get the site title and other data points that you might want. Then you can pass it to your actual header component, just as props. That way, you can still override things without...

[41:35] As a user that knows React but maybe doesn't know Gatsby yet, you can use that approach. You are separating your data concerns, even in your React components that are shadowed. That way, you can almost design your API around how you structure your components. As we see here now, the My Blog is gone, and "Hello Egghead" is instead being rendered.

Joel: [42:00] That's really cool.

John: [42:01] It's just based off the file system conventions. You can go to town whenever you want to, just modify perhaps the footer and the header. You can do so just by writing some React.

Joel: [42:15] As all this is changing over time -- because this is all in-flight at the moment -- where's the best place to watch this and see the progress?

John: [42:26] The Gatsby blog is one of the best places right now. There's also a talk that Chris Biscardi did before Gatsby days. We can give links for those. That's definitely one of the best places to start. Next week, we'll have the initial guides together, or at least the fit influx docs of how to get started with themes.

[42:46] Right now, unfortunately, we're reverse engineering the way it works, but we'll have a guide to get started for everyone at different Gatsby levels. You can use it that way. One cool part about the themes, too, is that they essentially act as a site that you can compose together.

[43:06] Aside from making your path resolution more flexible, it's just like building a site. You don't have to learn a lot of new concepts, aside from thinking about it as a theme author. You have to expose an API for your end user. Aside from that, it's just building the site.

Joel: [43:27] All the stuff that you did looked really straightforward to me. Once I learned Yarn workspaces, all the structure of this, it's just logical. It just makes logical sense. I think if you want to, you can feel free to push this.

[43:42] If you want to push this to a branch, or did you use a starter? I don't know. It would be nice to have this, and then the folks watching could reference it, too.

John: [43:50] We can push it to a branch. It's all in Git. One of the things, too, that's important to also note is Yarn workspaces aren't required. It's just one type...

Joel: [44:01] It just makes it easier, right?

John: [44:03] use this workflow. You can Yarn link a thing. If you want, you can just publish it to NPM and install it in your starter. The one part of this, you want your start to live, because it's still Gatsby starters. They're just Git repos.

[44:16] A lot of times, we'll potentially want the starter itself to live in a separate repo. That way, when it just clones everything down, until at least we support sub-pathing for...

Joel: [44:26] This is like a development mode, basically, but it's not necessarily how you publish it for general audience consumption.

John: [44:35] Right, yeah. This is what you develop against, but you'll then still have your starter repo.

Joel: [44:40] It's like a plugin, though. With a Gatsby plugin, you make a plugins folder, and then you develop it separately, too.

John: [44:48] Yeah, exactly.

Joel: [44:52] That's awesome, John. I appreciate the demo. I'm going to just probably expand on your demo to make our thing into a full-blown theme next week. We have a few minutes. Your video froze in a very fun way.

[45:12] We have audio, and I was going to say, if anybody had any questions about the themes, now's a good time to ask. John Otander is the inventor, creator of MDX. Is that how you would describe it? That's probably how I'd describe it.

John: [45:29] Co-creator, I guess.

Joel: [45:31] Co-creator. Also, did quite a bit in terms of tachyons. That's one of the things I know. You're like an unsung hero of mine. I don't think you get enough credit for all this awesome work you do. If anybody has any questions about themes, MDX, or programming computers in general, I think it's a pretty good opportunity.

[45:51] Feel free to type them in the chat, use the key eye feature, or whatever, if anybody has anything. Otherwise, how's working at Gatsby so far? How's your boss? You can tell us. We won't tell him.

John: [46:05] It's a blast, man. I get to work on what I'm passionate about for my day job. I have to pinch myself sometimes. It's pretty sweet.

Joel: [46:13] As a company, I've really just enjoyed what they've been doing. Then seeing you join, one, it really aligns into my own personal selfish interests, because I'm all about MDX and Gatsby right now. The way that we publish on the Internet, I think, I'm in a nice state of flux. I love this stuff. It's really cool to see you in the mix.

[46:38] We don't have any more questions, so I'll let you all get back to it. Thanks a lot. Appreciate it. Thanks, Ian, for your presence and your dutiful monitoring of the chat, and thanks, Jason.

Jason: [46:51] No problem.

Joel: [46:52] [laughs] Talk to you all soon.

John: [46:54] Thanks for having me. I'll have a faster computer next time.

Joel: [46:57] All right, sounds good. Requisition a request. See you.