Gatsby: The ultimate guide with examples

In this comprehensive Gatsby tutorial, we’ll tell you everything you need to know about the popular React-based framework, including what it is, how to use it, and what distinguishes Gatsby from other static site generators.

We’ll cover the following in detail:

What is Gatsby?

is a free, open-source, React-based framework designed to help developers build performant websites and apps. Put simply, Gatsby is a static site generator that leverages React.

Why would you need a framework on top of a framework (or library)? Isn’t React supposed to help developers build websites and apps? This is a reasonable question that is often posed when discussing .

React is a library that is meant to provide a certain set of core functionality for developers to leverage. It is intended to be lightweight and broadly applicable. Gatsby, on the other hand, is a static progressive web app (PWA) generator that offers code and data splitting out of the box.

What are static sites?

Static sites have been around for a very long time. In fact, they are probably the original website: just HTML, CSS, and JavaScript. They are not rendered during runtime; there is no server-side code, no database, etc.

A static site generator is a tool that generates static sites. With regard to JS frameworks and libraries, these usually generate HTML content on the client side during runtime. Static site generators generate this content during build time. Then, once loaded, React takes over, and you have a single-page application!

Getting started with Gatsby

To get started using Gatsby, download the Gatsby CLI: npm i -g gatsby. This command-line tool enables you to generate, run, and build a Gatsby application.

To get up and running quickly, you can use the . After cloning this (click the Use Template button to create your own copy, then do a git clone of your new repo), run npm install and then gatsby develop. This will generate a fully active Gatsby application running on .

If you’re running Node v18 you may get the following error:

You must provide the URL of lib/mappings.wasm by calling SourceMapConsumer.initialize({
'lib/mappings.wasm': ... }) before using SourceMapConsumer

Developing your site with Gatsby

To get off the ground, I used the . I forked this from GitHub and renamed the repo. Then I cloned it and used the Gatsby CLI to build. In a very short time, I was up and running on localhost with a live and hot-reloading application.

The structure of the code is very simple. You have three folders inside the src directory: components, images, and pages. The images directory contains a couple png’s that are used in the site. The components directory contains several components of note.

First, the layout.js component. It is a wrapper component designed to provide styling and functionality across the application. This kind of pattern is very popular in React.

You will notice that there is a binding called {children} in the center of the component:

/**
 * Layout component that queries for data
 * with Gatsby's useStaticQuery component
 *
 * See: https://www.gatsbyjs.com/docs/use-static-query/
 */
import * as React from "react"
import PropTypes from "prop-types"
import { useStaticQuery, graphql } from "gatsby"
import Header from "./header"
import "./layout.css"
const Layout = ({ children }) => {
  const data = useStaticQuery(graphql`
    query SiteTitleQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)
  return (
    <>
      <Header siteTitle={data.site.siteMetadata?.title || `Title`} />
      <div
        style={{
          margin: `0 auto`,
          maxWidth: `var(--size-content)`,
          padding: `var(--size-gutter)`,
        }}
      >
        <main>{children}</main>
        <footer
          style={{
            marginTop: `var(--space-5)`,
            fontSize: `var(--font-sm)`,
          }}
        >
          © {new Date().getFullYear()} &middot; Built with
          {` `}
          <a href="https://www.gatsbyjs.com">gatsbyjs</a>
        </footer>
      </div>
    </>
  )
}
Layout.propTypes = {
  children: PropTypes.node.isRequired,
}
export default Layout

Is Gatsby dead?