Today we’re excited to announce the general release of Gatsby’s new file system Route API!
Since its earliest days Gatsby created individual routes for files inside the pages folder and programmatically created pages via APIs that are exposed inside gatsby-node.js. With the introduction of our new File System Route API you’re now able to move this route creation logic out of gatsby-node.js and into the file name of a file inside the pages folder. Meaning that for most route creation use cases you won’t need a gatsby-node.js file anymore!
This new method for creating pages and routes makes getting started with Gatsby dramatically faster and simpler, whether as an individual developer or as a team.
If you want to head right into it, install the latest version of Gatsby (via npm install gatsby@latest) and follow the reference documentation. Also, be sure to take a look at the extensive example in the monorepo.
Otherwise, read on to find two short examples of what a migration to the new File System Route API could look like.
Migration: Client-only routes
In order to create user authenticated portions for your site you’ll need to create “client-only routes” in your Gatsby app. The client-only routes & user authentication documentation explains this concept.
Until now, you had to use the onCreatePage API in gatsby-node.js or use gatsby-plugin-create-client-paths. The example below assumes that you want your client-only portion to be available at /app on your website.
Updating Gatsby
To leverage the new possibilities you’ll need to update to a Gatsby version that is 2.26.0 or later.
Or run:
Removing onCreatePage
To create a matchPath for the /app route (while having a file at src/pages/app.js) you used to use:
You’re now able to completely remove the onCreatePage API call from gatsby-node.js. Instead, you’ll need to create a folder called app inside src/pages and move the existing src/pages/app.js file into there. Lastly, to create a splat route (same as /app/*) you’ll need to rename the file to [...].js.
The new path is now: src/pages/app/[...].js.
Migration: Programmatically created pages
The File System Route API abstracts away the explicit usage of createPages in gatsby-node.js by translating your file name into these same API calls under the hood. For most use cases, this greatly reduces boilerplate code that you otherwise would have to write to create pages programmatically. (Please see the FAQ at the end for a list of current limitations and how you can help us solve them).
In this short example a project similar to gatsby-starter-blog will be converted from createPages usage to the new File System Route API. We encourage you to open the reference documentation in another tab while following along.
Updating Gatsby
As explained in the previous example, update Gatsby to the latest version.
Removing createPages
You can remove the createPages call from your gatsby-node.js file:
At the end your gatsby-node.js file should only contain:
Moving and renaming the page template
The template to create each blog post is located at src/templates/blog-post.js and has the following contents:
Move the file to src/pages and rename it to {MarkdownRemark.fields__slug}.js. The file contents can stay the same. The previous createPage call iterated over the collection of MarkdownRemark nodes and set the path as post.fields.slug:
This is now translated to src/pages/{MarkdownRemark.fields__slug}.js in the file name itself.
FAQ
If your question isn’t listed below or you have any other issues/feature requests, please head over to the umbrella issue on GitHub. Please also let us know if you absolutely need a feature and why you need it. We might be able to move it up the prioritization list.
Can I pass custom properties into pageContext?
When using the createPage function you’re able to pass custom properties into the context object of each page. This isn’t possible at the moment.
Can I use custom variables for the file name?
Defining custom variables/fields inside the file isn’t possible at the moment, e.g. if you want to use {something}.js for your file name and then define something as MarkdownRemark.fields__slug. Therefore you’ll have to follow the syntax of {Model.field__nestedField}.
Can I use syntax XYZ?
Please see the reference documentation and their respective syntax categories.
Webinar on December 10th
Want to see a demo of how the new Route API makes spinning up a Gatsby project faster and easier? Join us on December 10th for our webinar Getting Started with Gatsby!