Gatsby: The Definitive Guide

Chapter 6. Programmatic Page Creation

In the previous chapter, we took a close look at how Gatsby enables the retrieval of arbitrary data from a variety of sources, whether that means a local filesystem, an external database or service, or a CMS or commerce platform. Thanks to source plugins, we can easily populate our Gatsby pages and components with external data.

But it’s often the case that we want the creation of our Gatsby pages to be dictated by the data rather than manually creating the pages first and populating them with data later. What happens when the pages in our Gatsby site depend on the data we retrieve in order to exist? How do we take GraphQL data and generate pages based on arbitrary response data?

One of Gatsby’s most important features, and one of the chief reasons for its success, is its capacity to perform programmatic page creation, in which pages depend on and are created according to GraphQL data. For instance, the home page of a blog might be manually created, but its archive pages and individual article pages likely rely on external data. As such, as developers, we can’t predict how many pages there might be, since the number of blog posts is arbitrary.

Thanks to the gatsby-node.js file and the createPages API, we can now create not only manual pages that contain data but also generated pages that depend on external data to exist. Through these mechanisms, we can implement rich Gatsby sites that don’t just contain static content; they also dynamically ...