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:

• onPreBootstrap e.g. implemented by gatsby-plugin-typography
• sourceNodes e.g. implemented by gatsby-source-wikipedia
  • within this createNode can be called multiple times, which then triggers onCreateNode.
• (the first schema build happens here)
• resolvableExtensions for filetype/language extensions eg gatsby-plugin-typescript
• createPages e.g. implemented by page-hot-reloader
  • within this createPage can be called any number of times, which then triggers onCreatePage
• onPreExtractQueries e.g. implemented by gatsby-transformer-sharp and gatsby-source-contentful
• (schema update happens here)
• extract queries from components where the queryCompiler replaces page GraphQL queries and StaticQueries
• The queries are run, and the pages are written out
• onPostBootstrap is called (but it is not often used)

Build sequence

(to be written)

Client sequence

(to be written)

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