Ecosystem

Design

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.