Part of what makes Gatsby sites so fast is that a lot of the work is done at build time and the running site isstatic content served from a CDN. During the build process, Gatsby creates paths to access pages, handlingrouting for you. Creating navigation for a Gatsby app requires an understanding of what those paths are and how they’re generated.

Often your application will include routes that are not known at build time. This includes routes that need authentication or for dynamic content. To handle those pages, you can make use ofclient-only routes using@reach/router which is built into Gatsby.

Creating routes

Routes can be created in three ways:

• By creating React components insrc/pages
• By using theFile System Route API to programmatically create pages from GraphQL and to create client-only routes.
• By implementing the APIcreatePages in your site’sgatsby-node.js. (Plugins can also implementcreatePages and create pages for you.)

Define routes insrc/pages

Gatsby generates pages for each.js file insidesrc/pages. The browser path is generated from the file path.

Add this component tosrc/pages/index.js to create a home page for your site.

For example,src/pages/contact.js creates the pageyoursite.com/contact, andsrc/pages/home.js creates the pageyoursite.com/home. This works at whatever level the file is created at. Ifcontact.js is moved to a directory calledinformation, located insidesrc/pages, the page will now be created atyoursite.com/information/contact.

The exception to this rule is any file namedindex.js. Files with this name are matched to the root directory they’re found in. That meansindex.js in the rootsrc/pages directory is accessed viayoursite.com. However, if there is anindex.js inside theinformation directory, it is created atyoursite.com/information.

Note that if a particular directory does not have anindex.js file, then that root page is not created, and attempts to navigate to it will land you on a404 page. For example,yoursite.com/information/contact may exist, but that does not guaranteeyoursite.com/information exists.

Using the File System Route API

Other than creating single-page routes insrc/pages you can also create multiple pages from a model based on the collection of nodes within it. To do that, use curly braces ({ }) in the file path to signify dynamic URL segments that relate to a field within thenode.

Use the File System Route API when you want to programmatically create pages from your GraphQL data, e.g. to create individual blog post pages for your blog. With this API you can control the file path and queried data by adding some extra notation to the names of your files without touching or creatinggatsby-node.js whatsoever.

For example, assuming you have a model calledProduct:

• src/pages/products/{Product.name}.js => /products/burger

See theFile System Route API documentation for more detail.

Usinggatsby-node.js

The File System Route API should be enough to get you through most use cases but if you need extra control, e.g. for passing data viapageContext or modifying thepath, you can useGatsby Node APIs, including thecreatePages function, inside yourgatsby-node.js file. This function will give you access to thecreatePage action, which is at the core of programmatically creating a page. Here’s an example for creating pages from Markdown files sourced by Gatsby’s data layer:

The data for creating these pages doesn’t necessarily have to come from Gatsby’s internal GraphQL data layer. For example, you can source local files or make async calls to remote APIs. For more information, please seeCreating and Modifying Pages.

path must not be pre-encoded (ie. usingencodeURI) however unicode characters are supported. So for a path like/exámple pass the string directly. Do not passencodeURI('/exámple') or/ex%C3%A1mple. If you receive pre-encoded paths from your CMS you may want to run them throughdecodeURI first to ensure the special characters (eg.%C3%A1) are turned back into unicode.

Conflicting Routes

Since there are multiple ways to create a page, different plugins, themes, or sections of code in yourgatsby-node file may accidentally create multiple pages that are meant to be accessed by the same path. When this happens, Gatsby will show a warning at build time, but the site will still build successfully. In this situation, the page that was built last will be accessible and any other conflicting pages will not be. Changing any conflicting paths to produce unique URLs should clear up the problem.

Nested Routes

If your goal is to define paths that are multiple levels deep, such as/portfolio/art/item1, that can be done directly when creating pages as mentioned inRoutes defined insrc/pages.

Alternatively, if you want to create pages that will display different subcomponents depending on the URL path (such as a specific sidebar widget), Gatsby can handle that at the page level usinglayouts.

Linking between routes

In order to link between pages, you can usegatsby-link. Usinggatsby-link gives you built inperformance benefits.

Alternatively, you can navigate between pages using standard<a> tags, but you won’t get the benefit of prefetching in this case.

Gatsby will handle scroll restoration for you in most cases. To track and restore scroll position in additional containers, you canuse theuseScrollRestoration hook.

Creating authentication-gated routes

For pages dealing with sensitive information, or other dynamic behavior, you may want to handle that information server-side. Gatsby lets you createclient-only routes that live behind an authentication gate, ensuring that the information is only available to authorized users.

Performance and Prefetching

In order to improve performance, Gatsby looks for links that appear on the current page to perform prefetching. Before a user has even clicked on a link, Gatsby has started to fetch the page it points to.Learn more about prefetching.