gatsbyjs.com

What is Gatsby about?

Gatsby is a React framework for building websites from components and structured content. It can collect data from files, content management systems, APIs, and other services; organise that data through a GraphQL layer; and use it to create pages with static, deferred, server-side, or client-side rendering.

Gatsby is the framework. gatsbyjs.com is its official website and documentation hub. That distinction matters because the framework’s architecture, packages, and repository are the subjects of this guide, while the domain is where the project publishes its documentation.

A Gatsby project commonly brings several concerns into one workflow:

• React components define the interface and reusable page elements.
• Source plugins import content and data from local or remote systems.
• Gatsby normalises sourced records into nodes in its data layer.
• GraphQL queries select the fields needed by pages and components.
• Page APIs and templates turn data into routes.
• Rendering settings determine when each page is produced.

How Gatsby relates to React

React provides Gatsby’s component model. Developers compose layouts, navigation, templates, and interactive features from React components, while Gatsby supplies the surrounding framework for routing, data sourcing, page creation, asset processing, and production output.

Gatsby is therefore neither a replacement for React nor merely a component library. It is an opinionated website framework built around React. Teams can apply familiar JSX, component composition, props, state, and browser-side interaction while using Gatsby-specific APIs for data and rendering.

What Gatsby adds around React

Concern	React provides	Gatsby adds
Interface	Components and state	Page conventions, layouts, and build integration
Data	Application-level fetching choices	A normalised data layer and GraphQL query workflow
Routes	Building blocks for an application	File-based pages, programmatic page creation, and client-only routes
Output	Browser-rendered interfaces	Static, deferred, and request-time page rendering
Integrations	A general JavaScript ecosystem	Gatsby plugins, themes, starters, and framework lifecycle APIs

This structure can suit a React team building a content-heavy public website. It may be unnecessary when a small project has little content integration or when its requirements are primarily those of a client-rendered application.

The data layer and GraphQL

Gatsby’s data layer is designed to give different content sources a common query interface. Source plugins retrieve records and create Gatsby nodes. Gatsby then makes those nodes available through a GraphQL schema that pages and components can query.

A site might combine Markdown files, images, a headless content system, and selected service data. Instead of making every page understand each source’s original response format, Gatsby can expose the relevant records through a shared graph.

A typical content path looks like this:

1. A file, service, or content platform holds the original material.
2. A source plugin imports that material during Gatsby’s data-sourcing process.
3. Gatsby represents the imported records as nodes and builds a schema.
4. GraphQL queries request the fields required by a page or component.
5. A template uses the query result to produce the page.
6. Gatsby renders the page according to its selected rendering mode.

GraphQL is central to Gatsby’s sourced-data workflow, but it does not replace every ordinary React value. Component props, local state, browser events, and client-side requests can still exist outside the build-time graph. The useful question is whether Gatsby’s shared schema simplifies the content that must be assembled into pages.

The data layer also introduces work. Teams need to understand source behaviour, node relationships, schema changes, and query dependencies. A graph that unifies several systems can be valuable, but its build cost and maintenance burden should be tested with representative content rather than inferred from a starter site.

Source plugins and the wider extension model

Source plugins connect Gatsby to data. They can read local files or integrate content systems and services, then create nodes that participate in the GraphQL layer. This makes them distinct from plugins that add processing, analytics, styling, image support, or other lifecycle behaviour.

Gatsby packages reusable work in three related forms:

• Plugins add a source, transformation, integration, or framework capability.
• Themes package reusable Gatsby configuration and functionality that sites can extend.
• Starters provide an initial project that developers copy and adapt.

A starter can shorten setup, but its dependencies and conventions become the adopting team’s responsibility. A theme can keep functionality consistent across sites, but teams should understand what it controls. A plugin can avoid custom integration code, although its compatibility and maintenance must be evaluated individually.

The existence of a large plugin category does not prove that a particular package supports a team’s Gatsby version, data source, or deployment model. A practical assessment should identify the exact packages required, inspect their documentation and repository activity, and test them inside the proposed architecture.

Rendering options in Gatsby

Gatsby began with a strong association with static-site generation, but its documentation now defines several rendering choices. These can be selected by page, allowing a public article, a large archive, a request-dependent route, and an application area to use different production models.

Rendering option	When the page is produced	Suitable question to ask
Static Site Generation (SSG)	During the build	Is the page’s required content available before deployment?
Deferred Static Generation (DSG)	When a deferred page is first requested	Can this page be excluded from the initial build, and does the host support Gatsby DSG?
Server-Side Rendering (SSR)	At request time, using getServerData	Does the response require request-time data or context?
Client-side route	In the browser for an application path	Is this section intentionally app-like, and what is available before JavaScript finishes?

Static and deferred pages

SSG produces HTML and related assets during the build. It is a natural option for content whose inputs are known in advance. Generated files can be straightforward to distribute, but a large page count, expensive queries, numerous content sources, or heavy image work may increase build demands.

DSG postpones selected pages until their first request. This can reduce the number of pages created during the initial build, especially when a site has a long tail of infrequently requested content. It also requires a deployment environment that implements Gatsby’s deferred-generation behaviour; it is not equivalent to uploading only static files to any host.

Request-time and browser rendering

SSR generates a response at request time through Gatsby’s getServerData API. It can serve pages whose output depends on current request-time information, but it introduces server execution, caching decisions, failure handling, and infrastructure requirements that a purely static page avoids.

Client-side routes support application sections handled in the browser. They can coexist with generated public pages, but teams should examine loading states, navigation, accessibility, and the content available before client-side code runs. Public discoverability should not be assumed merely because a browser route eventually displays the right information.

No rendering label guarantees speed or search visibility. Results depend on page design, JavaScript, assets, data sources, caching, hosting, and implementation quality. Gatsby gives teams several architectural options; it does not remove the need to measure them.

Images and content production

Images often sit inside the same content pipeline as text and structured records. Gatsby plugins can source image files, transform them, and connect processed assets to page queries. Components can then render the selected image data as part of a page template.

A useful editorial workflow separates responsibilities:

• Editors manage titles, body content, metadata, and image references in the chosen source.
• Source plugins import those records and referenced assets.
• Gatsby’s data layer connects content nodes to the required image data.
• Queries request only the fields and image variants needed by a template.
• Components provide captions, alternative text, dimensions, and layout behaviour.
• The production build verifies that records, assets, and routes resolve together.

Image processing can improve consistency, but it is still build work. Teams should test the real number and size of assets, confirm how changes affect rebuilds, and preserve meaningful alternative text from the editorial source. A plugin cannot decide whether an image is informative, decorative, or appropriately described.

Where Gatsby can fit well

Gatsby is particularly relevant when a project already uses React and needs to assemble content from several systems. Its data graph can provide a consistent layer between those sources and the page templates that consume them.

Common situations worth evaluating include:

• Documentation or editorial sites that combine files, images, and a content platform.
• Marketing sites with reusable React components and structured page records.
• Multi-source publishing projects that benefit from one query interface.
• Existing Gatsby sites built around page APIs, GraphQL, and established plugins.
• Large content collections where selected pages may be candidates for DSG.
• Sites mixing generated public pages with request-time or client-side sections.

Gatsby may be a less direct fit when a project has one simple content source, does not benefit from a normalised graph, or needs an application architecture centred primarily on request-time and client-side operations. That is an architectural judgment, not a verdict on framework quality.

Build and deployment tradeoffs

Static generation moves work before deployment. Gatsby may need to retrieve source data, construct its schema, execute queries, create pages, process images, bundle code, and write output. The duration and resource requirements depend on the real project.

A representative evaluation should record:

Test area	What to verify
Content scale	Page count, node count, relationships, and realistic record sizes
Source reliability	Authentication, rate limits, failures, and repeatable retrieval
Queries	Schema stability, query cost, and errors after content changes
Images	Processing volume, memory use, output size, and editorial metadata
Rendering	SSG output, DSG first requests, SSR responses, and client-route loading
Deployment	Support for every chosen mode, caching behaviour, and failure recovery

A small demonstration cannot establish how a full catalogue will behave. Teams should test clean builds, incremental changes where supported, content-source outages, and pages at both the common and extreme ends of the data set.

DSG can shift work away from the initial build, while SSR shifts work to requests. Those are changes in timing and operational responsibility, not free performance improvements. The chosen host must support the required Gatsby behaviour, and the team should understand what happens during a cold request or upstream failure.

Gatsby, Astro, and other alternatives

Gatsby and Astro can both appear in evaluations for content-driven websites, but they organise projects differently. Gatsby makes React, its GraphQL data layer, source plugins, and page-generation APIs central. Astro should be assessed on its own documented architecture rather than treated as a faster or newer answer by default.

Gatsby deserves closer consideration when a team wants React throughout the interface, needs to query several normalised content sources, relies on Gatsby integrations, or maintains an established Gatsby codebase. Another framework may be simpler when that graph and plugin lifecycle would add structure without solving a real content problem.

A useful comparison builds the same representative slice in each candidate: one content source, one complex page, a listing, image handling, navigation, and the intended deployment mode. Compare developer comprehension, build behaviour, browser output, accessibility, hosting requirements, and maintenance ownership. Avoid declaring a universal winner from default templates.

Founder and official community resources

In an official Gatsby community Q&A published on 2 April 2020, Kyle Mathews was identified as “Founder @ GatsbyJS.” That dated attribution describes his historical role in that source; it should not be read as a claim about Gatsby’s current leadership.

Gatsby’s documentation directs developers to official community channels for different needs:

• Discord is listed as a place to ask the community for developer help.
• GitHub Discussions supports project and feature discussion.
• The contribution documentation explains ways to participate in the project.
• The maintained gatsbyjs/gatsby repository contains the framework source, packages, issues, and contribution history.

These resources help readers verify documentation, ask implementation questions, and inspect public project work. Their existence should not be converted into unsupported claims about response times, package longevity, or future plans.

What teams should decide before adopting Gatsby

1. Map the content. Identify every source, the relationships between records, the update frequency, and which pages consume each field. This reveals whether Gatsby’s normalised GraphQL layer solves a meaningful coordination problem.

2. Assign a rendering mode to representative pages. Confirm which pages can be static, which might be deferred, which require getServerData, and which are deliberately client-side. Verify that the deployment target supports the resulting mix.

3. Audit the concrete dependency set. Check required source plugins, transformation plugins, themes, starters, and image tooling against the project’s Gatsby version. Prototype uncertain integrations before making them architectural dependencies.

4. Test a production-shaped workload. Gatsby offers a coherent React and content framework, but its suitability comes from alignment with the team’s data, pages, integrations, and hosting model—not from broad promises about speed, search rankings, or effortless scale.