Skip to main content

Gatsby Lifecycle APIs

Gatsby provides a rich set of lifecycle APIs to hook into its 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

The following model gives a conceptual overview of how data is sourced and transformed in the process of building a Gatsby site:

  title: Home
  description: Gatsby tips

Content is often organized in systems like databases, content management systems, files, or external APIs.

Any source of data can be connected to Gatsby through plugins or using Gatsby's APIs.

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