Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Pages and Routing

Pages and File System Routing

Create Gatsby pages from files in src/pages, learn how file names map to URLs, nested folders, index and 404 pages, the Head API and the File System Route API.

In Gatsby, a file is a route. Put a React component in src/pages and it becomes a page with a URL that matches the file path. There is no router to configure. This convention keeps small sites trivial and large sites predictable: to find the code for /docs/install/, you open src/pages/docs/install.js.

This lesson covers how file names turn into URLs, how to set the page title and metadata with the Head API, and how the File System Route API creates many pages from one file. The Gatsby code is read-only; a runnable stand-in implements the path mapping.

Files become pages

File URL
src/pages/index.js /
src/pages/about.js /about/
src/pages/blog/index.js /blog/
src/pages/blog/first-post.js /blog/first-post/
src/pages/404.js shown for unknown URLs
src/pages/contact-us.js /contact-us/

A real page:

JSX
// src/pages/about.js (real Gatsby, read-only)
import * as React from "react"
import { Link } from "gatsby"

const AboutPage = () => (
  <main>
    <h1>About us</h1>
    <p>We write about coffee.</p>
    <Link to="/">Back home</Link>
  </main>
)

export default AboutPage

export const Head = () => (
  <>
    <title>About us</title>
    <meta name="description" content="Who we are and what we brew." />
  </>
)

Rules to remember:

  • The file must default-export a React component.
  • File names should be lowercase with dashes. Gatsby lowercases and normalizes paths, but consistent naming avoids surprises on case-sensitive hosts.
  • Files starting with an underscore or ending in .test.js or .spec.js are ignored in src/pages, so you can keep tests beside pages.
  • Only code in src/pages creates pages by itself. Pages from data come from createPages.

Setting the title with the Head API

In Gatsby 5 each page can export Head. Gatsby renders it into the document <head> for you, during the build and in the browser:

JSX
export const Head = ({ data, location }) => (
  <>
    <title>{data.site.siteMetadata.title} | About</title>
    <link rel="canonical" href={`https://example.com${location.pathname}`} />
  </>
)

Head receives the same props as the page (location, data, params, pageContext). Only title, meta, link, script, style, base and noscript elements are allowed inside. It replaces the older react-helmet approach for most sites.

Nested routes

Folders give you nested URLs:

TEXT
src/pages/
  index.js              -> /
  docs/
    index.js            -> /docs/
    install.js          -> /docs/install/
    guides/
      deploy.js         -> /docs/guides/deploy/

A folder with an index.js owns the folder URL itself. A folder with no index simply has no page at that URL (visitors get a 404).

The File System Route API

For collections of pages generated from data, Gatsby lets you put the GraphQL type and field in the file name. The curly braces mark a dynamic part:

JSX
// src/pages/products/{Product.slug}.js (real Gatsby, read-only)
import * as React from "react"
import { graphql } from "gatsby"

const ProductPage = ({ data }) => (
  <main>
    <h1>{data.product.name}</h1>
    <p>{data.product.price} USD</p>
  </main>
)

export const query = graphql`
  query ($id: String) {
    product(id: { eq: $id }) {
      name
      price
    }
  }
`

export default ProductPage

For every Product node Gatsby creates a page at /products/<slug>/ and passes id as a query variable automatically. Adding a product to your data source creates a new page on the next build. Other forms exist: {Product.name__en} for nested fields, and {Product.slug} mixed with static folders. This is the quickest way to build product, post or doc pages without writing gatsby-node.js. You need the GraphQL ideas from GraphQL basics in Gatsby to use it.

Stand-in: map file paths to URLs

This stand-in is not Gatsby's router, but it implements the same rules for static pages and for {Type.field} collection routes.

JS Stand-in: files to routes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Add another product object and run again: a new page appears without touching any other file, just like a new node in Gatsby.

Stand-in: a page is a function

A page component renders HTML, and Head contributes the document head. This stand-in composes the two into a full document, the way Gatsby does when it writes each index.html.

JS Stand-in: render a page with a head

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Always add a 404.js page. In production, Gatsby serves it for unknown URLs. In development you also see a built-in page that lists all existing routes, handy for checking what the file system produced.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file becomes the URL /docs/install/?

    Files in src/pages map to URLs by their path. Components and static are not routed.
  2. 2. What must a page file export?

    The default export is the page component. Optionally Head and query are named exports.
  3. 3. What does a file named {Product.slug}.js do?

    The File System Route API creates a page per node of that type.
  4. 4. Where do you set the document title in Gatsby 5?

    Pages export a Head component that Gatsby renders into the document head.

Summary

  • A default-exported component in src/pages becomes a page; the path gives the URL.
  • index.js owns its folder, 404.js is the not-found page, underscore and test files are ignored.
  • Export Head to set titles, meta tags and canonical links per page.
  • {Type.field}.js creates a page for every node of a type, with id passed to the query.
  • Pages from files cover static routes; data-driven pages can also be created in code.

Next: Dynamic Routes and Client-Only Pages