Skip to main content

Gatsby Lifecycle APIs

Gatsby provides a rich set of lifecycle APIs to hook into Gatsby’s bootstrap, build, and client runtime operations.

Gatsby’s design principles include:

  • Conventions > code but use low-level primitives to build conventions with code.
  • Extracting logic and configuration into plugins should be trivial and encouraged.
  • Plugins are easy to open source and reuse. They’re just NPM packages.

High level Overview

Bootstrap sequence

During “bootstrap” gatsby:

  • reads gatsby-config.js to load in your list of plugins
  • initializes its cache (stored in /.cache)
  • pulls in and preprocesses data (“source and transform nodes”) into a GraphQL schema
  • creates pages in memory

    • from your /pages folder
    • from your gatsby-node.js if you implement createPages/createPagesStatefully (e.g. templates)
    • from any plugins that implement createPages/createPagesStatefully
  • extracts, runs, and replaces graphql queries for pages and StaticQuerys
  • writes out the pages to cache

In development this is a running process powered by Webpack and react-hot-loader, so changes to any files get re-run through the sequence again, with smart cache invalidation. For example, gatsby-source-filesystem watches files for changes, and each change triggers re-running queries. Other plugins may also perform this service. Queries are also watched so if you modify a query your development app is hot reloaded.

The core of the bootstrap process is the “api-runner”, which helps to execute APIs in sequence, with state managed in Redux. Gatsby exposes a number of lifecycle APIs which can either be implemented by you (or any of your configured plugins) in gatsby-node.js, gatsby-browser.js or gatsby-ssr.js.

The sequence of the main bootstrap Node API lifecycles are:

Build sequence

(to be written)

Client sequence

(to be written)


Please see the links along the left under “REFERENCE” for the full API documentation.


edit this page on GitHub