Gatsby 5.16: Static Generation With Per-Page Escape Hatches

What Gatsby Actually Builds

Gatsby is a React framework that compiles your site into static files at build time. The README describes it as combining the speed of static-site generation with the control of dynamically rendered sites. The core mechanism is a build step that runs your React components, collects data, and emits HTML, CSS, and JavaScript that you can host on a CDN. The output is not a server application. It is a folder of files. That is the central fact that determines everything else about the framework. You do not run Node at request time unless you explicitly choose a rendering option that requires it.

The GraphQL Data Layer and Source Plugins

Gatsby pulls data from any source: Markdown files, headless CMSs like Contentful and WordPress, or REST and GraphQL APIs. The README states that you use source plugins to load data, then develop against a uniform GraphQL interface. This means your components query data with GraphQL, regardless of where the data physically lives. The uniformity is the selling point. A team can switch from WordPress to Contentful without rewriting every page component, because the query layer stays the same. The cost is that you must learn GraphQL, and you must trust that a source plugin exists for your specific backend. If no plugin exists, you write your own, which is a real integration task.

Three Rendering Options, One Build Pipeline

The README lists three rendering options: Static Site Generation (SSG), Deferred Static Generation (DSG), and Server-Side Rendering (SSR). You choose them per page. SSG is the default: the page is built once at build time and served as a static file. DSG means the page is not generated during the initial build; it is generated on demand when first requested, then cached. SSR means the page is rendered on each request by a server. This granularity is the framework's most distinctive feature. It lets you keep most of a site static while making only the dynamic parts server-rendered. The trade-off is operational: SSR and DSG require a Node server or a hosting platform that supports them, which breaks the 'host anywhere' promise that pure SSG offers.

Getting Started With npm init gatsby

The README gives a four-step quickstart. First, run npm init gatsby and name the project, for example 'My Gatsby Site'. Second, cd into the directory and run npm run develop. This starts a development server at http://localhost:8000. Third, edit src/pages/index.js and the browser updates in real time. That is the entire local setup. There is no configuration file to create manually; the CLI scaffolds the project with defaults. For deployment, the README points to a Netlify button that creates a new repository, links it to a site, and sets up automatic rebuilds on push. The simplicity is real, but it hides the complexity that appears later when you add plugins, configure a CMS, or try to set up DSG or SSR.

Performance Features That Come for Free

The README claims that Gatsby automates code splitting, image optimization, inlining critical styles, lazy-loading, and prefetching resources. These are build-time optimizations, not runtime ones. The result is that a Gatsby site often scores well on performance audits without manual tuning. The claim is plausible because the build step has full knowledge of the site's pages and can precompute what each page needs. The limitation is that these optimizations only apply to the static parts. A page using SSR falls back to server-rendered HTML, and the same automated prefetching may not apply. So the performance benefit is not uniform across all rendering modes.

Where Gatsby Is the Wrong Tool

Gatsby is built for content-rich sites: blogs, marketing pages, e-commerce catalogs, dashboards that are mostly static. If your application is a real-time dashboard with user-specific data, or a SaaS product with authenticated routes, the static-first model fights you. You would need to make every dynamic page SSR, which means running a server, and at that point the static generation advantage disappears. The README's own example of 'user dashboards' is misleading, because a dashboard that changes per user cannot be pre-rendered. You would have to use SSR for every such page, and then you are paying server costs and losing the CDN-only hosting benefit. Also, the build step itself can become slow on large sites, though the README does not mention build times.

Alternatives and Their Different Approaches

The most direct alternative is Next.js, which also supports SSG, SSR, and client-side rendering, but it does not use a GraphQL data layer by default. Next.js lets you fetch data in getStaticProps or getServerSideProps with plain JavaScript, so there is no uniform query interface. The difference is architectural: Gatsby centralizes data access through GraphQL, while Next.js leaves data fetching to the developer. That means Gatsby gives you a consistent pattern but requires learning GraphQL and finding source plugins. Next.js gives you flexibility but more decisions per page. Another alternative is Astro, which uses a component island model and supports multiple frameworks, but the submitted material does not describe Astro, so I cannot compare it further. The choice depends on whether you want the data layer enforced or free-form.

Maintenance, Licensing, and Version Support

The repository is archived: no, and the last push was February 2026, with gatsby@5.16.1 released then. The license is MIT, which means you can use it in commercial projects without paying a fee. The README links to a version support page that explains plans for each version, but it does not state the exact support window. That is a gap you must check on the site before adopting Gatsby for a long-lived project. The migration guides from v2 to v3, v3 to v4, and v4 to v5 show that upgrades are a normal part of the lifecycle, and each major version requires a migration effort. The frequency of releases (5.15.0 in August 2025, 5.16.0 in January 2026, 5.16.1 in February 2026) suggests active maintenance, but it also means you should track release notes to avoid surprises.

Editorial conclusion

Adopt Gatsby if you are building a content-heavy site, a blog, or a marketing page with React and you want static output by default with the option to opt into SSR or DSG for specific routes. Skip it if your application is mostly dynamic, user-specific, or real-time, because the static-first model adds complexity without benefit. Before committing, verify that the plugins you need for your CMS or data source are maintained for Gatsby 5, and check the version support policy on gatsbyjs.com/docs/reference/release-notes/gatsby-version-support to see how long your chosen major version will receive updates. The next step is to run npm init gatsby and build a starter site, then test your actual data source with the relevant source plugin before you invest in a full migration.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes