Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

The Gatsby CLI and Dev Server

Learn the Gatsby CLI: gatsby develop, build, serve, clean, useful flags, hot reloading, GraphiQL, environment variables, caching and incremental builds explained.

The Gatsby command line interface (CLI) is how you run your site. There are only a few commands, but each one does something different, and mixing them up is a common beginner mistake: the development server is not the production build, and they can behave differently. This lesson explains each command, the flags you will actually use, and how caching speeds up repeated runs.

All commands here are real Gatsby commands shown read-only. Stand-ins afterwards model the ideas in runnable JavaScript.

The four commands you use daily

Terminal
gatsby develop   # development server with hot reloading, port 8000
gatsby build     # production build into public/
gatsby serve     # serve the built public/ folder locally, port 9000
gatsby clean     # delete .cache and public

The Gatsby CLI at a glance

develop Live dev server on port 8000
build Optimized static site in public
1 / 2

gatsby develop

Starts a server at http://localhost:8000 with hot module replacement: save a component and only that part updates in the browser. It also serves GraphiQL at /___graphql. Pages are compiled on demand and JavaScript is not minified, so it is slower at runtime than production but quick to start.

Useful flags:

Terminal
gatsby develop -H 0.0.0.0     # listen on all interfaces (test on your phone)
gatsby develop -p 8001        # use another port
gatsby develop --https        # local HTTPS (needs a certificate setup)
gatsby develop --open         # open the browser on start

gatsby build

Runs the full pipeline described in What is Gatsby?: sources data, runs queries, renders every page to HTML, bundles and optimizes JavaScript and CSS, and writes everything to public/. Always run it before you deploy, and run it in CI to catch errors early: queries that fail in development often only show up in a full build.

Terminal
gatsby build
gatsby build --prefix-paths   # build for a site hosted under a path prefix
gatsby build --log-pages      # list created/deleted pages

gatsby serve

Serves the contents of public/ using a simple local server. Use it to check what visitors will really get, including real bundle sizes, caching and client-only routes.

Terminal
gatsby build && gatsby serve

gatsby clean

Deletes .cache and public. Use it after upgrading Gatsby or plugins, after renaming files in odd ways, or whenever a problem makes no sense.

Build output and the cache

Gatsby keeps results in .cache. When you run gatsby build again, unchanged data and pages can be reused, so a second build of a big site is much faster. Hosting platforms often persist .cache and public between deploys for this reason.

flowchart LR
  A["First build<br/>everything runs"] --> C[".cache saved"]
  C --> B["Second build<br/>only changes run"]
  B --> D["Faster"]

Caching is why a one-line edit does not require rebuilding thousands of pages from scratch.

Environment variables

Gatsby loads variables in two ways:

  • Variables in the shell are available in gatsby-config.js, gatsby-node.js and during the build via process.env.
  • Variables you want in browser code must start with GATSBY_. Gatsby inlines them into the JavaScript bundle, so they are public.

A real .env.development file:

TEXT
GATSBY_API_URL=http://localhost:4000
CMS_TOKEN=keep-this-private

Load files in gatsby-config.js with dotenv:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
require("dotenv").config({ path: `.env.${process.env.NODE_ENV}` })

module.exports = { plugins: [] }

CMS_TOKEN stays on the build machine. GATSBY_API_URL is shipped to every visitor.

Stand-in: simulate an incremental build

This stand-in is not Gatsby. It hashes every "page" input and only re-renders those whose hash changed, which is the core of how caches skip work.

JS Stand-in: incremental builds with hashes

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

No output.

Stand-in: a command dispatcher with flags

JS Stand-in: parse CLI flags

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

No output.

Reading errors

When a build fails, read the first error, not the last. Typical causes: a GraphQL query that asks for a field that does not exist (see GraphQL basics), browser-only code such as window used while rendering, or a plugin missing from gatsby-config.js. Because pages render in Node during the build, code that touches window or document must run inside useEffect or behind a check.

Run gatsby build && gatsby serve before every deploy that changes dependencies. Development mode forgives some mistakes that production does not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command previews the finished production output locally?

    gatsby serve serves public/ after gatsby build. It listens on 9000.
  2. 2. How must an environment variable be named to be readable in browser code?

    Only GATSBY_-prefixed variables are inlined into the browser bundle, so never put secrets in them.
  3. 3. What does gatsby clean delete?

    It removes the generated cache and build output, which Gatsby recreates.
  4. 4. Why might a bug appear only after gatsby build?

    Server-side rendering has no browser globals, so code using window outside effects fails in the build.

Summary

  • develop for coding, build for production output, serve to preview it, clean to reset.
  • The dev server offers hot reloading and GraphiQL on /___graphql.
  • .cache makes repeated builds faster because unchanged work is skipped.
  • Only GATSBY_-prefixed variables reach the browser, and they are public.
  • Build errors often come from queries or from browser-only code run during rendering.

Next: gatsby-config and the Node APIs