English for Gatsby Developers
Vocabulary for developers maintaining Gatsby sites — GraphQL data layer, source plugins, incremental builds, and SSR/DSG rendering modes — for teams working in English on legacy and current Gatsby projects.
Gatsby popularised pulling content from any source into a unified GraphQL layer and pre-rendering it to static HTML — a pattern many newer frameworks have since adopted in their own way. If you maintain an existing Gatsby site, or you’re onboarding onto one, you’ll run into vocabulary that’s specific to Gatsby’s architecture: source plugins, the data layer, and its various rendering modes. This guide covers the terms.
The GraphQL Data Layer
Data layer — Gatsby’s internal GraphQL API that unifies content from every configured source (markdown files, a CMS, an API) into one queryable schema. “Instead of writing separate fetch logic for our CMS and our local markdown files, we query both through Gatsby’s data layer with a single GraphQL query.”
Source plugin — a plugin that pulls data from a specific source (the filesystem, Contentful, a REST API) into the GraphQL data layer.
“We’re using
gatsby-source-filesystemfor our markdown posts andgatsby-source-contentfulfor our marketing pages — both end up queryable through the same GraphQL schema.”
Transformer plugin — a plugin that converts raw source data into a more useful shape — for example, turning raw markdown into an HTML AST that other plugins or queries can use.
“
gatsby-transformer-remarktakes the raw markdown from our source plugin and parses it so we can query the rendered HTML directly in GraphQL.”
Page query vs. static query — a page query runs at the top level of a page template and can accept variables (like a slug); a static query runs inside any component but cannot accept variables.
“We needed the data to depend on the current page’s slug, so it had to be a page query — a static query wouldn’t have access to that variable.”
Build and Rendering Vocabulary
gatsby-node.js
The gatsby-node.js file is where you programmatically create pages at build time — typically looping over data from the GraphQL layer and calling createPage for each item.
“Every blog post page is generated in
gatsby-node.js— we query all posts, loop over them, and callcreatePageonce per slug.”
Incremental Builds
Incremental builds only rebuild pages affected by a content or code change, rather than rebuilding the entire site from scratch every time.
“Before incremental builds, a single typo fix meant waiting twenty minutes for a full rebuild — now it only rebuilds the handful of affected pages.”
Server-Side Rendering (SSR) in Gatsby
Gatsby supports SSR for specific pages that need to render fresh data per request, alongside its default static generation for everything else.
“Most of the site is statically generated at build time, but the user dashboard uses SSR because its content depends on who’s logged in.”
Deferred Static Generation (DSG)
DSG generates a page on the first request after deploy, then caches it — a middle ground between fully static (built ahead of time) and fully server-rendered (built on every request).
“We used DSG for our long tail of rarely visited product pages — it kept the build fast without sacrificing the benefits of static hosting for pages that do get traffic.”
Plugins and the Ecosystem
gatsby-config.js — the central configuration file declaring source plugins, site metadata, and other plugins.
Image processing pipeline — Gatsby’s built-in system (gatsby-plugin-image and its predecessors) for generating responsive, optimised image variants at build time.
“We switched from manually exporting three image sizes to using the image processing pipeline — it generates the responsive variants automatically from one source file.”
GraphQL fragment — a reusable, named selection of GraphQL fields that can be included in multiple queries, avoiding repetition.
“We defined a
SeoFieldsfragment once and reused it across every page query that needs metadata, instead of repeating the same six fields everywhere.”
Migration and Legacy Talk
Content mesh — the broader idea Gatsby popularised, of composing content from multiple decoupled sources into one site, rather than relying on a single monolithic CMS.
“Our content mesh pulls from three different systems — a legacy CMS, a headless CMS for new content, and local markdown for documentation — all unified through Gatsby’s data layer.”
Framework migration — moving an existing Gatsby site to a newer meta-framework, often motivated by build times or a shrinking plugin ecosystem.
“We’re planning a framework migration off Gatsby over the next two quarters — mainly because build times have grown and community plugin maintenance has slowed.”
Explaining Gatsby Architecture to a Team
| Situation | Phrase |
|---|---|
| Explaining the data layer to a new hire | ”Everything — CMS content, markdown files, even our team roster spreadsheet — gets pulled into one GraphQL schema, so every page template queries data the same way.” |
| Justifying incremental builds | ”A content-only change now rebuilds in under a minute instead of twenty, because incremental builds only touch the pages affected by that change.” |
| Explaining a rendering mode choice | ”The dashboard page uses SSR because its content is per-user — everything else stays statically generated for speed.” |
| Discussing a migration decision | ”We’re not migrating because Gatsby is broken — it’s that our plugin ecosystem has stagnated and build times have grown past what we’re comfortable with.” |
Common Mistakes
- Calling every Gatsby query a “static query” — only queries with no variables qualify; page-level queries with variables are a distinct concept.
- Saying “Gatsby is just static site generation” without mentioning SSR and DSG support — the framework supports more rendering modes than pure SSG.
- Referring to
gatsby-node.jsas “the backend” — it runs at build time to generate pages, not as a runtime server.
Practice Exercise
- Explain, in two sentences, the difference between a source plugin and a transformer plugin.
- Write a short comment for a
gatsby-node.jsfile explaining why a specific page type uses DSG instead of full static generation. - Draft a short summary (3-4 sentences) justifying a decision to migrate a Gatsby site to a different meta-framework.