Gatsby Introduction and Installation — React Static Site Generator

In this tutorial, you will learn about Gatsby Introduction and Installation. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Gatsby: understand the React-based static site generator, install it, create a project, and explore the initial file structure for building blazing-fast websites.

In this lesson, you'll install Gatsby, create a new site, understand the project structure, and run the development server with hot reloading.

What You'll Learn

How to create a Gatsby site, understand the src/ directory structure, configure the dev server, and recognize Gatsby's data layer and build pipeline.

Why It Matters

Gatsby generates static HTML at build time, resulting in extremely fast page loads. It combines React components with a rich plugin ecosystem and GraphQL data layer.

Real-World Use

DodaTech's documentation site uses Gatsby because static generation produces HTML files that load instantly on Cloudflare's CDN without server-side processing.

flowchart LR
    A[Install Gatsby CLI] --> B[Create New Site]
    B --> C[Explore Structure]
    C --> D[Run Dev Server]
    D --> E[Build Static Files]
    style B fill:#639,color:#fff

Installation

Install the Gatsby CLI globally:

npm install -g gatsby-cli

Create a new Gatsby site:

gatsby new my-gatsby-site
cd my-gatsby-site
gatsby develop

The dev server starts at http://localhost:8000. Gatsby also exposes a GraphiQL explorer at http://localhost:8000/___graphql.

Project Structure

my-gatsby-site/
├── src/
│   ├── pages/       # Route components (.js, .tsx)
│   ├── components/  # Reusable components
│   ├── images/      # Image assets
│   └── templates/   # Page templates for programmatic creation
├── static/          # Static assets (served as-is)
├── gatsby-config.js # Site configuration and plugins
├── gatsby-node.js   # Node API for custom build logic
└── package.json     # Dependencies

First Page

Create a new page at src/pages/about.js:

import React from 'react';

export default function About() {
  return <h1>About Gatsby</h1>;
}

Output: Visit http://localhost:8000/about. Gatsby creates a route for every .js file in src/pages/.

Common Mistakes

1. Not installing the CLI globally: gatsby-cli must be installed globally or run via npx gatsby.
2. Forgetting to restart after config changes: Changes to gatsby-config.js or gatsby-<a href="/backend/nodejs/">Node.js</a> require restarting the dev server.
3. Using React APIs without import: Gatsby uses React. Always import React and the hooks you need.
4. Editing files outside src/ while developing: Other directories like static/ don't trigger hot reload.
5. Not checking the GraphiQL explorer: The data layer is powerful. Explore available data at /___graphql.

Practice Questions

1. What command creates a new Gatsby site? Answer: gatsby new my-gatsby-site. It scaffolds a project with default plugins and configuration.

2. What port does the dev server use? Answer: Port 8000. Access the GraphiQL explorer at http://localhost:8000/___graphql.

3. Where do page components live? Answer: In src/pages/. Each .js file becomes a route based on its filename.

4. What is the purpose of gatsby-node.js? Answer: It exposes Gatsby's Node APIs for custom build logic: creating pages dynamically, modifying Webpack config, and adding resolvers.

Challenge

Create a Gatsby site with three pages (/, /about, /contact) and add navigation between them using Link from gatsby.

Mini Project

Scaffold a Gatsby site, add a src/pages/blog.js page, install the gatsby-source-filesystem plugin, and configure it to read Markdown files from a content/ directory.

FAQ

What's Next

Learn about Gatsby Pages and Routing to understand file-based routing and page creation in detail.