This course has been updated! We now recommend you take the Intermediate Gatsby, v2 course.
Transcript from the "Schema Customization" Lesson
[00:00:00]
>> Jason Lengstorf: Now that we've got MDX loading, we are ready to actually start using it. So the first thing we wanna do is to make sure that the data types we are using are predictable. Like we could go in and try to extend mark down or do something like that.
[00:00:18] But honestly that gives us a bunch of noise and what we really want is just to get the stuff that we need and nothing else, without any nesting or needing to know what the terms are, nothing's inside of a front matter column. I just wanna be able to get a page and get the title and the body of it, and all that stuff and just kind of be done.
[00:00:40] That makes it nice and predictable. The first thing we're gonna do is we're gonna create a schema customization, which we're gonna do by hooking into the schema customization. It's called create schema customization API. And this one gives us some actions that we can work with. So the only action that we actually need here is the createTypes action.
[00:01:09] And what this means is that we can just go into the GraphQL layer of Gatsby and tell it that something exists. This is really handy, because what it means is I can say I want an abstract type that is of my definition, that does only what I wanna do.
[00:01:23] It only has the data that I want in it. So I want my docs pages to have a type called docs page. And in my docs page, I wanna be able to query these. So I'm going to implement the node type, and the node type is Gatsby's, like core type.
[00:01:41] Any data that exists will become a node inside of Gatsby. By telling Gatsby that the Docs Page is a node, that means that we get a bunch of stuff for free. It’s gonna give us filtering and querying on different field names and all sorts of good stuff. The other thing that we want is, we don’t want it to create any extra fields that we don’t tell it to.
[00:02:01] I’m gonna tell it not to infer. Don't worry too much about how all this stuff works under the hood like GraphQL is its own rabbit hole and it can go pretty deep. Basically what we're telling Gatsby right now is that we want this type to exist. We want to be able to query it like every other Gatsby data type, and we don't want you to create any fields unless we tell you they exist.
[00:02:25] So the first one we need is an ID, pretty much every node is gonna need an ID. We use it for keys, we use it for direct lookups. Then I want to create a title and my title's gonna be a string. And so the type in GraphQL is going to be ID or string, and then the exclamation point marks it as being required.
[00:02:47] So we're saying that an ID is required, a title is required. In this particular case, everything is gonna be required. There are no optional values. I'm gonna set up the path to be a string as well. And I want to know when this page was updated, because a nice thing on docs is to know, is this page like is it maintained or is this not been updated since 2015.
[00:03:08] So I'm gonna set this as date type and it's required. And then Gatsby gives us some helpers for this. So I'm gonna use the date format helper here to signify the Gatsby that I wanna be able to do things like format the date based on relative time or using a date string of my choosing.
[00:03:30] And then finally, we want the body of the page and that's also gonna be a string. So upon creating this, what this means is that I can go and start up my site. And we'll do yarn workspace theme-dev develop. And once this gets up and running, I can go back to my page,
[00:03:54]
>> Jason Lengstorf: And refresh, and now I have a query for old docs page. And if I look in to the nodes, I can see that we've got the ID. We've got the title, path updated, and we can see the helpers here on how to format a date that showed up and we get the body.
[00:04:12] And so if I run this, it doesn't error out. Now we haven't given it any data. But Gatsby now knows that, that type should exist. And so it's just giving us an empty set. This is really powerful because what it means is in our themes, we can define an empty state like, you don't have any docs here, go create them here.
[00:04:32] Rather than having to catch an error when Gatsby says like, no docs found, type is not defined. So this is a really nice kind of layer of polish you can add to anything you're building and Gatsby, and this does not necessarily need to be for custom types. You can do this for the front matter on your your mark down files or something.