Creating and Modifying Pages
Gatsby makes it easy to programmatically control your pages.
Pages can be created in three ways:
- By creating React components in the
src/pagesdirectory. (Note that you must make the component the default export.)
- By using the File System Route API to programmatically create pages from GraphQL and to create client-only routes.
- In your site’s
gatsby-node.jsfile, by implementing the API
createPages. (Plugins can also implement
createPagesand create pages for you.)
Pages can also be modified by you after their creation. For example, you could change the
path to create internationalized routes (see gatsby-theme-i18n for instance) by implementing the API
Note: For most use cases you’ll be able to use the File System Route API to create pages. Please read on if you need more control over the page creation or consume data outside of Gatsby’s GraphQL data layer.
To see what pages are being created by your code or plugins, you can query for
page information while developing in GraphiQL. Paste the following query in
the GraphiQL IDE for your site. The GraphiQL IDE is available when running
your site’s development server at
context property accepts an object, and you can pass in any data you want the page to be able to access.
You can also query for any
context data you or plugins added to pages.
NOTE: There are a few reserved names that cannot be used in
context. They are:
Often you will need to programmatically create pages. For example, you have markdown files where each should be a page.
This example assumes that each markdown page has a
path set in the frontmatter
of the markdown file.
Imagine a scenario where you could query for all the parameters your template would need in the
gatsby-node.js. What would the implications be? In this section, you will look into this.
In the initial approach you have seen how the
gatsby-node.js file would have a query block like so :
id as an access point to query for other properties in the template is the default approach. However, suppose you had a list of products with properties you would like to query for. Handling the query entirely from
gatsby-node.js would result in the query looking like this:
You are now requesting all the data you need in a single query (this requires server-side support to fetch many products in a single database query).
As long as you can pass this data down to the template component via
pageContext, there is no need for the template to make a GraphQL query at all.
Your template file would look like this:
pageContext props in the template component can come with its performance advantages, of getting in all the data you need at build time; from the createPages API. This removes the need to have a GraphQL query in the template component.
It does come with the advantage of querying your data from one place after declaring the
However, it doesn’t give you the opportunity to know what exactly you are querying for in the template and if any changes occur in the component query structure in
gatsby-node.js. Hot reload is taken off the table and the site needs to be rebuilt for changes to reflect.
Gatsby stores page metadata (including context) in a Redux store (which also means that it stores the memory of the page). For larger sites (either number of pages and/or amount of data that is being passed via page context) this will cause problems. There might be “out of memory” crashes if it’s too much data or degraded performance.
If there is memory pressure, Node.js will try to garbage collect more often, which is a known performance issue.
Page query results are not stored in memory permanently and are being saved to disk immediately after running the query.
We recommend passing “ids” or “slugs” and making full queries in the page template query to avoid this.
Another disadvantage of querying all of your data in
gatsby-node.js is that your site has to be rebuilt every time you make a change, so you will not be able to take advantage of incremental builds.
Gatsby core and plugins can automatically create pages for you. Sometimes the default isn’t quite what you want and you need to modify the created page objects.
A common reason for needing to modify automatically created pages is to remove trailing slashes.
To do this, in your site’s
gatsby-node.js add code similar to the following:
Note: There’s also a plugin that will remove all trailing slashes from pages automatically: gatsby-plugin-remove-trailing-slashes.
Note: If you need to perform an asynchronous action within
onCreatePage you can return a promise or use an
The automatically created pages can receive context and use that as variables in their GraphQL queries. To override the default and pass your own context, open your site’s
gatsby-node.js and add similar to the following:
On your pages and templates, you can access your context via the prop
pageContext like this:
Page context is serialized before being passed to pages. This means it can’t be used to pass functions into components and
Date objects will be serialized into strings.
When using the Content Sync feature on Gatsby Cloud, an optional parameter,
ownerNodeId, can be passed to the
createPage action to allow greater control over where content is previewed. By passing a value to
ownerNodeId, you can ensure that Content Sync will redirect content authors to the page they intend to preview their content on. The value of
ownerNodeId should be set to the id of the node that’s the preferred node to preview for each page. This is typically the id of the node that’s used to create the page path for each page.
In specific cases, you might want to create a site with client-only portions that are gated by authentication. For more on how to achieve this, refer to client-only routes & user authentication.