# Introduction to Gatsby

> Learn how Gatsby uses React, file-based routing, GraphQL, plugins, and multiple rendering modes to build and deploy modern websites.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2018-11-28 | Updated: 2026-07-18 | Topics: [React](https://flaviocopes.com/tags/react/) | Canonical: https://flaviocopes.com/gatsby/

Gatsby is an open source framework for building websites with [React](https://flaviocopes.com/react/).

It started as a static site generator and became popular during the rise of the [JAMstack](https://flaviocopes.com/jamstack/). Static generation is still the default, but modern Gatsby also supports Deferred Static Generation (DSG) and Server-Side Rendering (SSR).

The current major version is Gatsby 5. You can check the [official release notes](https://www.gatsbyjs.com/docs/reference/release-notes/) and [version support page](https://www.gatsbyjs.com/docs/reference/release-notes/gatsby-version-support/) before starting or upgrading a project.

## How Gatsby works

You build pages using React components.

Gatsby can source content from Markdown, a headless CMS, a database, a web API, or the local filesystem. Source plugins add that data to Gatsby's data layer, where you can query it with GraphQL.

You do not have to use the data layer for every value. A page can also import local data or fetch data at runtime like any other React application.

Gatsby offers three main rendering modes:

- **Static Site Generation (SSG)** creates HTML during the build
- **Deferred Static Generation (DSG)** creates selected pages when they are first requested
- **Server-Side Rendering (SSR)** renders selected pages for each request

You can read the details in the official [rendering options guide](https://www.gatsbyjs.com/docs/how-to/rendering-options/).

SSG output can be hosted as static files. DSG, SSR, redirects, and Gatsby Functions need a host and adapter that support their runtime requirements.

## Create a Gatsby site

Install a current Node.js LTS release, then run:

```sh
npm init gatsby
```

The initializer asks for the project name, JavaScript or TypeScript, styling, a content source, and optional features.

When it finishes, move into the new folder and start the development server:

```sh
cd my-gatsby-site
npm run develop
```

Open <http://localhost:8000>. Gatsby uses port 8000 by default and refreshes the page when you save a change.

This is the setup recommended by Gatsby's current [quick start](https://www.gatsbyjs.com/docs/quick-start/). A global `gatsby-cli` installation is no longer required for this workflow.

## Project structure

A Gatsby project normally includes:

- `src/pages`, where files become pages
- `src/components`, for reusable React components
- `static`, for files copied directly to the site
- `gatsby-config.js` or `gatsby-config.ts`, for site metadata, plugins, and configuration
- `gatsby-node.js` or `gatsby-node.ts`, when you need Gatsby's Node APIs
- `public`, the generated production output
- `.cache`, Gatsby's generated build cache

Do not edit `.cache` or `public` by hand. Gatsby recreates them.

## Create a page

Files inside `src/pages` become routes.

For example, create `src/pages/about.js`:

```js
export default function AboutPage() {
  return <main>About this site</main>
}

export function Head() {
  return <title>About</title>
}
```

The page is available at `/about/`.

The exported `Head` component is Gatsby's built-in way to add page metadata. A separate React Helmet plugin is not required for this basic use case.

## Link to another page

Use Gatsby's `Link` component for internal navigation:

```js
import { Link } from 'gatsby'

export default function IndexPage() {
  return <Link to="/about/">About</Link>
}
```

Use a normal `<a>` element for links to other websites.

## Add CSS

You can import a global CSS file from a component:

```js
import './index.css'
```

Gatsby also supports CSS Modules. Name the file `index.module.css`, import it as an object, and use the generated class names:

```js
import * as styles from './index.module.css'

export default function IndexPage() {
  return <h1 className={styles.title}>Hello</h1>
}
```

## Use plugins

Gatsby plugins can source data, transform content, process images, create sitemaps, add offline support, and integrate other services.

Install a plugin with npm, then add it to the `plugins` array in the Gatsby configuration.

For example:

```sh
npm install gatsby-plugin-sitemap
```

```js
module.exports = {
  siteMetadata: {
    siteUrl: 'https://www.example.com'
  },
  plugins: ['gatsby-plugin-sitemap']
}
```

Always follow the plugin's current setup instructions. Some plugins require options or companion packages.

Browse the [official plugin library](https://www.gatsbyjs.com/plugins/) to see what is available.

## Does Gatsby automatically create a PWA?

No. A Gatsby site is not automatically an offline-capable Progressive Web App.

You can add a web app manifest with `gatsby-plugin-manifest` and offline support with `gatsby-plugin-offline`. The offline plugin installs a service worker, so test its caching behavior carefully before using it in production.

See the official [`gatsby-plugin-manifest`](https://www.gatsbyjs.com/plugins/gatsby-plugin-manifest/) and [`gatsby-plugin-offline`](https://www.gatsbyjs.com/plugins/gatsby-plugin-offline/) documentation.

## Build and preview the site

Create a production build:

```sh
npm run build
```

Preview that build locally:

```sh
npm run serve
```

For a site that only uses SSG, the generated static files are in `public`.

For DSG, SSR, or Functions, use an appropriate [Gatsby adapter](https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting/adapters/) and follow the host's Gatsby deployment instructions.