Gatsby: React Framework for Static Sites
/gatsby
Gatsby is a real option for React developers building a content site, not a framework past its prime — the performance defaults, automatic code splitting, image optimization, and prefetching, work without extra tuning. The main trade-off: the GraphQL data layer and the Lerna monorepo structure are extra concepts a solo developer has to learn on top of React itself.
What is Gatsby
Gatsby is an open-source React framework for building websites that compile to static files ahead of time, with per-page options to switch to deferred or server-side rendering. Source plugins pull data from Markdown files, headless CMS solutions such as Contentful or WordPress, or REST and GraphQL APIs, exposing all of it through one GraphQL query layer inside your React components.
Core Gatsby features
- ✓A single GraphQL query layer sits in front of every data source — Markdown files, a headless CMS such as Contentful or WordPress, or a REST or GraphQL API endpoint — so page components query the same way no matter which system the content actually comes from.
- ✓Rendering is chosen per page: Static Site Generation, Deferred Static Generation, or Server-Side Rendering, instead of one strategy for the whole site.
- ✓Code splitting, image optimization, critical CSS inlining, lazy loading, and resource prefetching all run automatically at build time.
- ✓Output is a real React app, not flat HTML, so pages can behave like dashboards or e-commerce flows, not just blog posts.
- ✓No server process is required to run the built site — it's static files you can put on any CDN.
- ✓The codebase itself is a Lerna-managed monorepo that publishes many separate packages to npm.
What you can build with Gatsby
- •Content sites — blogs and marketing pages — pulled from Markdown or a headless CMS.
- •E-commerce storefronts and logged-in dashboards, since Gatsby output is a full React app.
- •Multi-source sites where content lives in more than one place (a CMS plus a REST API, say) and you want one GraphQL query for both.
- •Sites you want to host on a CDN for near-zero server cost, the way the README's Netlify example does.
Installing Gatsby and initializing a project
Run `npm init gatsby` to scaffold a project (the README's own example names it My Gatsby Site), then `cd my-gatsby-site/` and `npm run develop` to start the dev server. That's the full setup — no separate build step before you can start editing.
Building your first Gatsby site
With `npm run develop` running, the site serves at `http://localhost:8000`. Open the project folder in your editor and edit `src/pages/index.js` — the browser updates as you save. From there the README points to the official tutorial and the plugins directory for wiring up real data sources.
Strengths
- ✓One GraphQL interface no matter which data source is behind a given page — Markdown, a CMS, or an API.
- ✓Performance work (code splitting, image optimization, prefetching, critical CSS) happens automatically, not as a manual checklist.
- ✓Output is a full React app, so dashboards and e-commerce pages work the same way blog pages do.
- ✓Per-page rendering choice (SSG, DSG, SSR) instead of one trade-off for the entire site.
- ✓MIT license — no cost or copyleft obligation for commercial use.
Gatsby limitations and trade-offs
- △The GraphQL layer is central to how Gatsby works, so even simple content pulls mean writing GraphQL queries — an extra concept on top of React itself.
- △This repo is a Lerna monorepo publishing many packages separately to npm, which makes tracking compatible versions during upgrades more work than a single-package library.
- △Static Site Generation is still the default: content changes don't show up until the next build unless a page opts into Deferred Static Generation or Server-Side Rendering.
Gatsby alternatives
Frequently asked questions
Yes — the framework lives in the gatsbyjs GitHub organization and the source plugins and plugin ecosystem remain functional. The README does not state anything about release cadence or roadmap beyond that, so check recent commit activity yourself if pace of development matters for your decision.
Gatsby is released under the MIT License, so you're free to build and ship commercial products with it — sites, apps, whatever — without paying a licensing fee or having to open-source your own project's code in return, and the license text ships right in the repo.
Gatsby routes every data source — Markdown, a CMS, an API — through one GraphQL layer at build time, while Next.js fetches data per page in plain JavaScript and mixes static generation, server rendering, and incremental regeneration without requiring GraphQL. Next.js's per-page model is more flexible out of the box; Gatsby's GraphQL layer pays off once several data sources feed one site.
Building past a single static page in Gatsby means writing GraphQL queries to pull in Markdown, CMS, or API content, so some GraphQL familiarity is unavoidable. Copying a query from a starter gets you far without deep expertise, but the query syntax itself doesn't disappear.
No — the open-source framework in this repo builds the same way regardless of where you host the output, and the README does not tie it to any particular hosting platform. Any static host or CDN that can serve the build output works.
Gatsby's own docs include a dedicated guide for migrating a v4 site to v5, plus earlier guides for v3-to-v4 and v2-to-v3, so upgrading an existing Gatsby site is well documented. Migrating a site built on a different framework into Gatsby isn't covered by these guides and isn't clearly documented here.
The problem it solves
Pulling content from a CMS, Markdown files, and a couple of APIs into one site usually means writing a different data-fetching path for each source and gluing them together by hand. Gatsby's answer is a single GraphQL schema that source plugins feed into, so a page component queries one interface no matter where the underlying content actually lives.
Who should try it — and who should skip
Makes sense for React developers building a content site — blog, docs, marketing pages, a small storefront — that pulls from more than one data source, where a shared GraphQL layer actually removes work instead of adding it. Less sense for a two-page brochure site (a plain SSG or Next.js without GraphQL is simpler), or for anyone who picked Gatsby specifically for Gatsby Cloud's managed builds, since that product is gone.
Related repositories
Is gatsby worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of gatsby.