Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 36 ยท Getting Started

What Is Gatsby?

Learn what Gatsby is, how it turns React components and data into fast static pages, when to choose it, and how a build differs from a runtime server.

Gatsby is a framework for building websites with React. You write pages as React components, describe where your data comes from (Markdown files, a headless CMS, an API, a database), and Gatsby combines the two at build time into plain HTML, CSS and JavaScript files. Those files can be copied to any static host or a CDN, which makes the result fast, cheap to run and hard to break.

The idea behind this is simple: most pages on most sites do not change between two visitors. A blog post, a documentation page and a product landing page look the same for everyone, so why build them again on every request? Gatsby does the work once, ahead of time, and hands visitors finished pages. Once a page has loaded, React "hydrates" it and the site behaves like a normal single-page app with instant navigation.

This lesson explains the mental model you will use for the whole track. If you know React already, you will feel at home. If not, skim React basics first.

The build-time idea

A traditional server-rendered site runs code on every request. A single-page app ships JavaScript and renders in the browser. Gatsby moves the expensive work to the moment you run gatsby build:

flowchart LR
  A["Data sources<br/>Markdown, CMS, APIs"] --> B["Gatsby data layer<br/>(GraphQL)"]
  C["React page components"] --> D["gatsby build"]
  B --> D
  D --> E["Static HTML, CSS, JS<br/>in /public"]
  E --> F["CDN or static host"]
  F --> G["Visitor"]

Data and components meet once, during the build. Visitors only receive the output.

Because the output is static, you get several benefits:

  • Speed. A CDN can serve an HTML file in milliseconds, close to the visitor.
  • Security. There is no application server or database to attack at request time.
  • Cost. Hosting files is cheap, and traffic spikes do not need extra servers.
  • SEO. Search engines receive complete HTML, not an empty <div id="root">.
  • Reliability. If your CMS goes down, the already built site keeps working.

What Gatsby gives you

Gatsby is more than "React plus a build script". It bundles several ideas:

What Gatsby gives you

Pages Files in src/pages become routes
Data layer One GraphQL API for all sources
Plugins Source, transform, optimize
Images Resized, lazy, modern formats

Four building blocks you will meet in this track.

1 / 2

The most important piece is the data layer. Gatsby reads every source into a single graph of objects called nodes and exposes it through a GraphQL API. Your components do not care whether a title came from a Markdown file, Contentful or a JSON file: they ask for title the same way. You will learn it in GraphQL basics in Gatsby.

A page in real Gatsby

Here is the smallest real page. This code is read-only because the real Gatsby tool does not run on this site:

JSX
// src/pages/index.js  (real Gatsby, read-only)
import * as React from "react"

const IndexPage = () => {
  return (
    <main>
      <h1>Hello, Gatsby</h1>
      <p>This page was rendered to HTML during the build.</p>
    </main>
  )
}

export default IndexPage

export const Head = () => <title>Home</title>

Saving that file in src/pages is all it takes to get a page at /. The Head export sets the document title and meta tags. Notice there is no router setup: file system routing does that for you.

A stand-in: build once, serve many times

The real build runs inside Node with Webpack. The following runnable stand-in is not Gatsby; it shows the core idea with plain JavaScript. A "build" step turns data plus a template function into finished HTML strings, and the "server" only looks them up.

JS Stand-in: a tiny static site generator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try adding a third post and watch the list of built files grow. The data changed, so you would rebuild. That is the trade-off of static generation: fresh data needs a new build (or a different rendering mode, covered later).

Hydration: static first, app second

After the HTML arrives, the browser downloads a small JavaScript bundle. React attaches event handlers to the existing markup (this is called hydration) and from then on clicking a link does not reload the page. Gatsby also prefetches the data and code for pages linked in the viewport, so the next click is almost instant.

JS Stand-in: why prefetching feels instant

Press Run (or Ctrl + Enter) to see the console output here.

No output.

When to choose Gatsby

Gatsby is a good fit for content-heavy sites (blogs, documentation, marketing pages, e-commerce catalogs) where many pages share a layout and data comes from files or a CMS. It is less suited to pages that must be personalized on every request, though you can combine static pages with client-side data fetching or with server-side rendering when a route needs it.

Gatsby 5 requires Node.js 18 or newer and uses React 18. Everything in this track targets Gatsby 5. Check the official release notes before upgrading across major versions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does Gatsby normally turn React components into HTML?

    Gatsby renders pages to static HTML during gatsby build, so the host only serves finished files.
  2. 2. What is the data layer in Gatsby?

    Plugins load data into nodes and Gatsby exposes them through one GraphQL API.
  3. 3. What is hydration?

    After the static HTML loads, React hydrates it so it becomes an interactive app.
  4. 4. Which statement is a drawback of purely static generation?

    Static pages are fixed at build time, so changed data requires a new build unless you add another rendering mode or client-side fetching.

Summary

  • Gatsby builds React pages and data into static files during gatsby build.
  • Static output is fast, secure, cheap to host and friendly to search engines.
  • The GraphQL data layer unifies every data source behind one API.
  • Hydration turns the static HTML into an interactive React app, with prefetching for instant navigation.
  • Fresh data needs a rebuild, unless you use other rendering modes.

Next: Install Gatsby and Create a Site