How Gatsby Works

A 2 minute read

Gatsby is a web compiler. It takes your React code and GraphQL queries and compiles them to static assets and data.

What does this look like? Typically, you write code that looks like this:

import React from "react"
import { graphql } from "gatsby"

export default props => (
  <div>Hello from {props.data.site.siteMetadata.author}!</div>
)

export const query = graphql`
  {
    site {
      siteMetadata {
        author
      }
    }
  }
`

Gatsby turns that into these:

<div id="___gatsby">
  <div style="outline:none" tabindex="-1" id="gatsby-focus-wrapper">
    <div>
      Hello from Sid!
    </div>
  </div>
</div>

{
  "componentChunkName": "component---src-pages-index-js",
  "path": "/",
  "result": {
    "data": { "site": { "siteMetadata": { "author": "Sid" } } }
  }
}

These are simplified for the purpose of this illustration. There are more files generated and the HTML includes a little more markup including an announcer for accessibility.

Of course, it also produces JavaScript including code for:

hydrating this static HTML into a client side React app
the Webpack runtime that is responsible for loading necessary JavaScript chunks in time
the Gatsby runtime that knows how to take the JSON blob from the example above and make the included query result data available to the component when that page is loaded

The result of this compilation does not include the GraphQL query we exported in our JSX above. This is because Gatsby compiles it out of your code. GraphQL queries are resolved at build time and their results are included in static JSON files.

Several moving parts make this possible together. Let’s list them and then dive deeper into each:

Gatsby Data Layer and GraphQL Compiler
Gatsby Plugin System and Lifecycle APIs
HTML Generation via React SSR
Gatsby Client Runtime

Gatsby Data Layer and GraphQL Compiler

Gatsby makes it possible to source data from several different sources (via plugins) including old school CMSes like WordPress, more modern CMSes like Sanity, databases, RESTful and GraphQL APIs and even services like Google Docs. Many of these do not support GraphQL out of the box, yet Gatsby makes it possible to consume them via GraphQL.

This requires a source agnostic and flexible data layer capable of GraphQL schema generation on the fly.

Gatsby Data Layer and GraphQL Compiler

Node Model