# Gatsby: a React framework that puts data behind GraphQL and ships static HTML

> Gatsby is an MIT-licensed React framework that sources content from Markdown, CMSs or APIs into a single GraphQL layer and renders pages as static HTML, with SSR and Deferred Static Generation available per page. The last push to the repository was on 2026-02-10.

**gatsbyjs/gatsby** — Gatsby is a React framework for fast, content-rich sites, pulling data from Markdown, headless CMSs, or APIs into a uniform GraphQL layer with static generation.

- Repository: https://github.com/gatsbyjs/gatsby
- Website: https://www.gatsbyjs.com
- Stars: 55,944 · Forks: 10,114
- Language: JavaScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/gatsbyjs-gatsby

## The problem Gatsby solves: content from many sources, one query layer

Most content sites start with files and end up with a database, a CMS, an image pipeline and a search index. Each of those has its own client, its own pagination model and its own caching behaviour. Gatsby's answer is to pull all of them into a build-time GraphQL schema. The README describes the workflow plainly: source plugins load your data, then you develop against what it calls a uniform GraphQL interface. A page component does not import a Markdown file or call a REST endpoint directly. It exports a page query, and the framework resolves that query against the aggregated schema during the build.

The audience is narrower than the marketing suggests. This is for teams building content-rich sites where the data is known at build time, and where the people writing pages are comfortable in React. The README frames it as helping professional developers create maintainable, content-rich websites. If your content lives in a database that changes per request and you cannot tolerate a rebuild, the GraphQL aggregation step buys you nothing.

## How the build pipeline turns source plugins into static HTML

The mechanism is a build-time data layer. Source plugins read from somewhere (Markdown files, a headless CMS, a REST or GraphQL API) and write nodes into a store. Those nodes define the GraphQL schema that page queries are validated against. When you run a build, the framework executes the queries, hands the results to React components as props, and renders the output to HTML files.

The README says you can choose rendering options per page: Static Site Generation, Deferred Static Generation and Server-Side Rendering. That per-page granularity is the interesting design decision. DSG defers rendering of a page until it is first requested, which keeps build times down on sites with tens of thousands of routes. SSR renders a page on each request, which reintroduces a server where the rest of the site has none. Mixing them means the deployment target has to support both static assets and a runtime, and the README does not describe what happens to DSG pages on a host that only serves files.

On the client side, the README states that the framework automates code splitting, image optimization, critical style inlining, lazy loading and prefetching. Those are defaults, not opt-ins, which is why a bare Gatsby build tends to score well on audits without configuration. The cost is that the build does more work, and the build is where all the time goes.

## Installing Gatsby and running a first page

The README gives a four-step local setup. The initializer is interactive and asks for a project name; the README uses "My Gatsby Site" as the example answer.

```bash
npm init gatsby
```

After the prompts finish, move into the generated directory and start the development server. The README's example directory name is my-gatsby-site, which follows from the name you gave it.

```bash
cd my-gatsby-site/
npm run develop
```

The README states the site is then running at http://localhost:8000. Open src/pages/index.js in an editor, save a change, and the README says the browser updates in real time. That is the whole first-run loop: no config file to write, no server to start separately.

For a deployed starting point, the README points at a Netlify deploy link for gatsby-starter-blog, which creates a new repository linked to a new site and rebuilds on every push. If you prefer to stay local, the repository also carries a starters/ directory and an examples/ directory with runnable projects such as examples/graphql-reference and examples/image-processing.

## Where the build-time model breaks down

The GraphQL schema is generated from your data, so a source that fails or returns an unexpected shape fails the build, not one page. That is a real operational difference from a server-rendered site, where a bad API response degrades a single route. Here it stops the whole deploy.

The second constraint is rebuild latency. Any content change means re-running the data layer and re-rendering pages. DSG softens this by deferring page rendering to first request, but the README does not claim it eliminates the rebuild, only that it changes when rendering happens. For a newsroom publishing continuously, the gap between an editor hitting save and the change appearing is a build duration, not a request.

The third is that a static deployment has no request-time context unless you add SSR or functions. The repository includes examples/functions-auth0, examples/functions-airtable-form and similar projects, so the pattern exists, but it is a separate layer from the page queries. If your site is mostly authenticated, per-user views, the build-time data layer is overhead you pay for and rarely use. The README is silent on rollback behaviour, so treat deploy recovery as something your host provides, not something the framework documents.

## Gatsby compared with Next.js on the same React foundation

Both are React frameworks with file-based routing and static output, so the difference is where the data layer sits. Gatsby builds a GraphQL schema at build time and expects page components to query it. Next.js has no equivalent aggregation step; you fetch data inside the component or a server function, and the framework renders what you return.

That single difference drives the rest. Gatsby gives you one schema across Markdown, a CMS and an API, which is genuinely useful when a site pulls from four places and you want one query syntax. Next.js gives you per-request flexibility without a schema to maintain, which is easier when content is dynamic or when you would rather not learn GraphQL to render a blog post.

Gatsby's per-page choice between SSG, DSG and SSR is closer to what Next.js offers than the static-site framing suggests. The practical split is the schema: if you want the build to validate every page query against every source, Gatsby is the stronger fit. If you want to fetch at request time and skip the build-time graph entirely, it is not.

## Maintenance, version support and what the MIT licence means here

The repository is not archived, and the most recent release listed is gatsby@5.16.1 on 2026-02-10, with gatsby@5.16.0 on 2026-01-26 and gatsby@5.15.0 on 2025-08-27 before it. The last push to master was on 2026-02-10, which is more than six months before today, so the cadence you should plan around is what the release notes show, not an assumption of daily commits.

The README links a version support document that describes plans for each major version, and separate migration guides for v4 to v5, v3 to v4 and v2 to v3. Those guides are the upgrade cost. A major bump means reading the guide and changing code, not just editing a version in package.json. The repository is a monorepo managed with lerna.json and yarn 1.22.19, so plugin and core versions move together.

The licence is MIT, which permits commercial use and modification with the copyright notice retained. That is a permissive licence, not a copyleft one, but it says nothing about the plugins you add: each source plugin carries its own licence, and the README does not enumerate them. Check the plugin you depend on before assuming the same terms apply.

## Conclusion

Gatsby fits content-heavy sites where the data already lives in Markdown, a headless CMS or an API, and where a team is comfortable writing GraphQL queries in page components. It is the wrong choice if you need per-request server logic on every route, if your content changes continuously and rebuild latency matters more than CDN cost, or if you do not want a build step between editing and publishing. Before adopting it, verify the version support page for the release line you plan to run, read the v4 to v5 migration guide if you already have a site, and confirm the source plugin for your CMS exists and is current. The repository is not archived, but the last push was on 2026-02-10, so check the release notes for what shipped after that date rather than assuming the master branch is moving daily.

## FAQ

### What is Gatsby in tech?

Gatsby is a free and open-source framework based on React that helps developers build websites and apps, combining static-site generation with the control of dynamically rendered sites. It pulls data from Markdown files, headless CMSs or REST and GraphQL APIs into a uniform GraphQL interface.

### How do I install Gatsby?

The README's local setup starts with npm init gatsby, which initializes a new project and asks for a name. You then move into the generated directory and run npm run develop, after which the README states the site is running at http://localhost:8000.

### What does Gatsby mean?

The README does not explain the origin of the name. In this repository it refers to the React-based framework maintained at gatsbyjs/gatsby, not to any other use of the word.

### What is Gatsby?

The README describes Gatsby as a free and open-source framework based on React that helps developers build websites and apps, using React and GraphQL regardless of where the data comes from.

## Sources

- [Official documentation](https://www.gatsbyjs.com)
- [Official README](https://github.com/gatsbyjs/gatsby#readme)
- [Project repository](https://github.com/gatsbyjs/gatsby)
- [Release notes](https://github.com/gatsbyjs/gatsby/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gatsbyjs-gatsby