Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Install Gatsby and Create a Site

Set up Node.js, run npm init gatsby, answer the starter questions, start the dev server and understand the scripts and dependencies of a new Gatsby 5 project.

Getting a Gatsby site running takes a few minutes. You need Node.js, a terminal and a code editor. This lesson walks through every step, explains what the generator asks you and what it writes to disk, and shows the commands you will type every day.

The commands below are real Gatsby commands and are shown read-only, because Gatsby cannot run inside this website. Runnable stand-ins after them show how the generator and scripts work in plain JavaScript.

Prerequisites

  1. Node.js 18 or newer (an LTS release is the best choice). Check with node --version.
  2. A package manager: npm ships with Node; Yarn and pnpm also work.
  3. Git is recommended, because some starters are fetched from Git repositories.
  4. A C/C++ toolchain is usually not needed any more: the image library sharp ships prebuilt binaries.
Terminal
node --version
npm --version

You do not need to install the Gatsby CLI globally. Modern projects keep it as a local dependency and run it through npm scripts. A global install is optional and only gives you the gatsby command anywhere.

Create a site with npm init gatsby

The recommended way is the official generator:

Terminal
npm init gatsby

It asks a handful of questions in your terminal:

Question What it does
What would you like to call your site? Sets siteMetadata.title
What would you like to name the folder? The project directory
Will you be using JavaScript or TypeScript? Chooses .js or .tsx files
Will you be using a CMS? Optionally adds a source plugin (Contentful, Sanity, WordPress, ...)
Would you like to install a styling system? Adds CSS Modules, Sass, styled-components, Emotion, Tailwind, ...
Would you like to install additional features? Image handling, Markdown, sitemap, RSS feed, manifest

You can also skip all questions by cloning a starter, which is just a complete Gatsby project in a Git repository:

Terminal
npx gatsby new my-site https://github.com/gatsbyjs/gatsby-starter-blog

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

Terminal
cd my-site
npm run develop

Open http://localhost:8000. Edit src/pages/index.js, save, and the browser updates without a reload (hot module replacement). Gatsby also exposes the data explorer GraphiQL at http://localhost:8000/___graphql; you will use it in GraphiQL and the data layer.

What the generated package.json contains

Open package.json and you will find something like this:

JSON
{
  "name": "my-site",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "develop": "gatsby develop",
    "start": "gatsby develop",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "gatsby": "^5.13.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

The typecheck script exists only in TypeScript projects. The important parts:

  • gatsby, react, react-dom are the three core dependencies. Plugins you add later appear next to them.
  • The scripts are shortcuts for the CLI commands covered in the Gatsby CLI and dev server.
  • "private": true stops you from publishing the site to npm by accident.

Stand-in: how a generator works

A project generator is conceptually a function from your answers to a set of files. This stand-in is not the Gatsby generator; it mimics the idea so you can see how answers change the output.

JS Stand-in: answers in, files out

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

No output.

Change language to "javascript" and rerun: the tsconfig.json file disappears and the page extension changes.

Run scripts by name

When you type npm run build, npm looks up the build key in scripts and runs that command with local binaries on the PATH. This stand-in reproduces the lookup.

JS Stand-in: how npm run finds a script

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

No output.

Common installation problems

  • Wrong Node version. Gatsby 5 refuses to run on old Node. Use nvm or a version manager to switch.
  • Peer dependency errors. Plugins list the Gatsby versions they support. Install plugin versions that match your Gatsby major version (gatsby-plugin-image for Gatsby 5 and so on).
  • Port 8000 already in use. Run npm run develop -- -p 8001.
  • Stale cache after strange errors. Run npm run clean, then try again. This deletes .cache and public.
  • Slow installs behind a proxy. Configure npm's proxy or registry before installing.

Commit package-lock.json (or yarn.lock) to Git. Reproducible installs matter because Gatsby, React and plugins must stay on compatible versions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new Gatsby project interactively?

    npm init gatsby runs the official generator that asks about language, CMS, styling and features.
  2. 2. What is a Gatsby starter?

    Starters are ready-made projects you can clone with gatsby new.
  3. 3. Which URL serves the dev site by default?

    gatsby develop listens on port 8000. gatsby serve uses 9000.
  4. 4. What should you try first when you see odd cache errors?

    gatsby clean removes .cache and public, which fixes most stale-cache problems.

Summary

  • You need Node 18+ and a package manager; the Gatsby CLI can stay a local dependency.
  • npm init gatsby asks about language, CMS, styling and features, then writes the project.
  • Starters are full projects you can clone with gatsby new.
  • package.json scripts wrap the CLI: develop, build, serve, clean.
  • gatsby clean is the first fix for cache trouble.

Next: Gatsby Project Structure