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.


Was this helpful? edit this page on GitHub