Part of what makes Gatsby sites so fast is that a lot of the work is done at build time and the running site is using mostly static content. During that process, Gatsby creates paths to access that content, handling routing for you. Navigating in a Gatsby app requires an understanding of what those paths are and how they’re generated.
Alternatively, your application may include functionality that cannot be handled at build time or through rehydration. This includes things like authentication or retrieving dynamic content. To handle those pages, you can make use of client-only routes using
@reach/router which is built into Gatsby.
Gatsby makes it easy to programmatically control your pages. Pages can be created in three ways:
- In your site’s gatsby-node.js by implementing the API
- Gatsby core automatically turns React components in
- Plugins can also implement
createPagesand create pages for you
See the Creating and Modifying Pages for more detail.
When Gatsby creates pages it automatically generates a path to access them. This path will differ depending on how the page was defined.
.js file inside
src/pages will generate its own page in your Gatsby site. The path for those pages matches the file structure it’s found in.
contact.js will be found at
home.js will be found at
yoursite.com/home. This works at whatever level the file is created. If
contact.js is moved to a directory called
information, located inside
src/pages, the page will now be found at
The exception to this rule is any file named
index.js. Files with this name are matched to the root directory they’re found in. That means
index.js in the root
src/pages directory is accessed via
yoursite.com. However, if there is an
index.js inside the
information directory, it is found at
Note that if no
index.js file exists in a particular directory that root page does not exist, and attempts to navigate to it will land you on a 404 page. For example,
yoursite.com/information/contact may exist, but that does not guarantee
Another way to create pages is in your
gatsby-node.js file using the
For more information on this action, visit the
createPage API documentation.
Since there are multiple ways to create a page, different plugins, themes, or sections of code in your
gatsby-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.
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 in Creating routes.
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 using layouts.
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 can use the
For pages dealing with sensitive information, or other dynamic behavior, you may want to handle that information server-side. Gatsby lets you create client-only routes that live behind an authentication gate, ensuring that the information is only available to authorized users.
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.