gatsby

Gatsby is an open-source, React-based framework for building static-site-generated and hybrid-rendered websites and applications. It pulls data from virtually any source — Markdown files, headless CMSs, REST or GraphQL APIs — into a unified GraphQL data layer, then compiles pages ahead of time for CDN-speed delivery.

Beyond pure static generation, Gatsby supports per-page rendering modes: Static Site Generation (SSG), Deferred Static Generation (DSG) for pages that can be built on first request, and Server-Side Rendering (SSR) for fully dynamic pages — all within the same project and build pipeline. This lets teams mix a marketing site, a blog, and dynamic dashboards without switching frameworks.

The framework automates the performance work developers would otherwise hand-roll: code splitting, image optimization via its own sharp-based image pipeline, critical CSS inlining, and link prefetching. A large ecosystem of source, transformer, and functionality plugins (for CMSs, image processing, SEO, analytics, and more) extends the core without touching application code.

What You Get

• A unified GraphQL data layer that sources content from Markdown, headless CMSs, REST, and GraphQL APIs through source plugins
• Per-page rendering control: Static Site Generation, Deferred Static Generation, and Server-Side Rendering in one project
• Automatic code splitting, image optimization, critical CSS inlining, and resource prefetching with no manual tuning
• A CLI (gatsby develop, gatsby build, gatsby serve) that drives the full develop/build/deploy lifecycle
• A large plugin ecosystem (source, transformer, and functionality plugins) for CMSs, image processing, SEO, and analytics
• File-based and programmatic page creation via the Node APIs (createPages, onCreateNode, etc.)

Common Use Cases

• Marketing sites and blogs sourced from Markdown or MDX with fast, CDN-served output
• Headless-CMS-backed sites (Contentful, WordPress, Sanity) that need static-site performance
• E-commerce storefronts that mix statically generated catalog pages with server-rendered cart/checkout pages
• Documentation sites that combine MDX content with custom React components
• Hybrid apps that need both instantly-cached marketing pages and dynamic, per-request pages in the same deploy

Under The Hood

Architecture Gatsby’s core (packages/gatsby/src) is organized around a Redux store (redux/) that holds the site’s data-layer state (nodes, pages, config), a set of xstate state machines (state-machines/, covering develop, data-layer, query-running, and waiting) that orchestrate the build/develop lifecycle, and a GraphQL schema/runner (schema/, query/graphql-runner.ts) that executes page queries against the sourced data. The CLI entry point (src/bin/gatsby.js) delegates to the separate gatsby-cli package, and each command (commands/build.ts, commands/develop.ts, commands/serve.ts) wires together bootstrap (bootstrap/index.ts, which loads config, plugins, and themes), the webpack build pipeline (utils/webpack/), and a worker pool (utils/worker/pool.ts) for parallelized query execution. Node-API plugins are invoked through utils/api-runner-node, giving third-party plugins hooks into node creation, page creation, and the webpack config without touching core internals — a change to the Redux state shape or the GraphQL schema-building step would ripple through nearly every downstream stage (querying, page-data writing, SSR/DSG bundle generation).

Tech Stack The package is TypeScript-first (typescript ^5.1, compiled via tsc for declarations and Babel for runtime output), targeting Node.js with React 18/19 as a peer dependency. Its data layer runs on graphql ^16 with custom GraphQL-Codegen tooling for typed query generation, redux 4.2 for state, and xstate ^4.38 for lifecycle orchestration. The build pipeline is built on webpack ~5.98 with a large set of loaders/plugins (babel-loader, css-minimizer-webpack-plugin, @vercel/webpack-asset-relocator-loader), plus @parcel/core for some bundling paths and sharp-based image processing (via a separate gatsby-plugin-sharp-adjacent pipeline). Config and plugin options are validated with joi schemas (joi-schemas/), and the CLI itself is a sibling gatsby-cli package using yargs.

Code Quality The repo is a Lerna-managed Yarn workspace monorepo with well over 200 __tests__ directories under packages/gatsby/src alone, run through Jest (root jest.config.js auto-discovers per-package __tests__ dirs and excludes built dist output). ESLint (extending google and eslint:recommended via @babel/eslint-parser) and Prettier are configured at the monorepo root and enforced through lint-staged/husky, and CircleCI runs the suite on every push. Error handling is centralized through a shared gatsby-cli reporter (report.panic, report.error) rather than ad-hoc console logging, and configuration/plugin-option validation goes through explicit Joi schemas rather than silent coercion — a deliberate, structured approach rather than loosely-typed JavaScript.

What Makes It Unique Gatsby’s distinguishing technical choice is unifying arbitrary content sources behind one GraphQL schema at build time, then letting individual pages opt into SSG, DSG, or SSR independently — most static-site tools commit a whole project to one rendering strategy. Its incremental builds and worker-pool-parallelized query execution (utils/worker/pool.ts) let large sites (tens of thousands of pages) rebuild only what changed rather than the whole site, and its source/transformer plugin model lets arbitrarily many data backends coexist in a single data layer rather than requiring a single hard-coded backend integration.