Gatsby File System Route API — Simplified Page Creation

In this tutorial, you will learn about Gatsby File System Route API. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn the Gatsby File System Route API for creating pages directly from file names and data, without manual gatsby-Node.js configuration for common patterns.

In this lesson, you'll understand how to use file naming conventions to create pages from data automatically.

What You'll Learn

How to use the File System Route API, create collection routes with {} syntax, access data params, and understand when to use this vs gatsby-node.js.

Why It Matters

The File System Route API eliminates boilerplate for common patterns. Many page types can be created without writing any gatsby-node.js code.

flowchart LR
    A[src/pages/] --> B[{file.name}.js]
    B --> C[Collection Route]
    C --> D[Auto-generated Pages]
    D --> E[/post-1/]
    D --> F[/post-2/]
    D --> G[/post-3/]
    style B fill:#639,color:#fff

Collection Routes

Create pages from data collections automatically:

// src/pages/{MarkdownRemark.frontmatter__slug}.js
import { graphql } from 'gatsby';
import React from 'react';

export default function BlogPost({ data }) {
  const post = data.markdownRemark;
  return (
    <article>
      <h1>{post.frontmatter.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
    </article>
  );
}

export const query = graphql`
  query($id: String!) {
    markdownRemark(id: { eq: $id }) {
      html
      frontmatter { title }
    }
  }
`;

Output: The filename {MarkdownRemark.frontmatter__slug}.js tells Gatsby to create one page per Markdown entry using the slug frontmatter field as the URL path.

Route Syntax

src/pages/{CollectionType.field}.js
src/pages/{CollectionType.field__subfield}.js
src/pages/{CollectionType.field__subfield}/nested.js

Double underscore separates nested fields: frontmatter__slug accesses frontmatter.slug.

Multiple Collection Routes

// src/pages/blog/{MarkdownRemark.fields__slug}.js
// src/pages/products/{ProductsYaml.slug}.js
// src/pages/users/{ContentfulUser.username}.js

Each file creates pages from different data sources. The collection type must match a Graphql type name.

Templating with Parent Routes

Create category-based hierarchies:

// src/pages/category/{ContentfulCategory.slug}/{ContentfulPost.slug}.js

Output: Posts are organized under category URLs like /category/tech/post-title/.

Accessing Page Context

Access additional data through the pageContext prop:

export default function Product({ data, pageContext }) {
  // pageContext includes:
  // - id: The GraphQL ID of the matched node
  // - ...plus any other fields from the route path
  return <div>Product: {data.productsYaml.name}</div>;
}

Common Mistakes

1. Using wrong collection type name: The type must match the exact GraphQL type name (e.g., MarkdownRemark, not Markdown).
2. Missing the $id parameter: The File System Route API passes id automatically. Your query must accept $id: String!.
3. Not restarting after creating route files: New file-based routes require a dev server restart.
4. Complex URL patterns in filenames: Deeply nested routes in filenames can be confusing. Keep paths simple.
5. Over-relying on FS Route API: For complex logic (pagination, related content, conditional page creation), use gatsby-node.js.

Practice Questions

1. What triggers page creation in the File System Route API? Answer: Filenames with {CollectionType.field} syntax. Gatsby creates one page per data entry.

2. How do you access nested frontmatter fields in route names? Answer: Use double underscore: {MarkdownRemark.frontmatter__slug} becomes frontmatter.slug.

3. What variable does the route pass to your page query? Answer: $id: String! which contains the GraphQL node ID of the matched entry.

4. When should you use gatsby-node.js instead of FS Route API? Answer: When you need pagination, multiple data sources combined, conditional page creation, or custom context beyond what the FS Route API provides.

Challenge

Use the File System Route API to create pages for a YAML products file. Create a product listing at /products/ and individual pages at /products/{ProductsYaml.slug}.

Mini Project

Migrate a blog from manual gatsby-node.js page creation to the File System Route API. Create routes for posts, author pages, and tag archives using the FS Route API wherever possible.

FAQ

What's Next

Learn about Creating Pages from CMS Data to build pages sourced from Contentful, WordPress, and other headless CMS platforms.