Introduction to Gatsby

Gatsby is an open source framework for building websites with React.

It started as a static site generator and became popular during the rise of the 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 and version support page 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.

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:

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:

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. 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:

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:

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:

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:

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:

npm install gatsby-plugin-sitemap

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 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 and gatsby-plugin-offline documentation.

Build and preview the site

Create a production build:

npm run build

Preview that build locally:

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 and follow the host’s Gatsby deployment instructions.

Related posts about react: