Skip to content
Get packs

Guide · Open source

How to use Gatsby: install, run and build your first site

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gatsby is a free, open-source framework built on React for making websites and web apps. It pulls data from sources such as Markdown files, headless CMSs, or REST and GraphQL APIs, then builds pages that load quickly. This guide shows you how to create a new Gatsby site, run it locally, and understand the features that set it apart.

Gatsbygatsbyjs/gatsby · ★ 55.9k · MIT

Quick start

  1. 1Check Node.js. Make sure Node.js is installed, since Gatsby's prerequisite is Node.js and npm runs the commands.
  2. 2Initialize the project. Run npm init gatsby and name the site "My Gatsby Site" when prompted.
  3. 3Enter the project folder. Run cd my-gatsby-site/ to move into the new site directory.
  4. 4Start develop mode. Run npm run develop and open http://localhost:8000 in your browser.
  5. 5Edit the index page. Open src/pages/index.js in your editor, make a change and save to see it update in the browser.
  6. 6Read the official tutorial. Follow the Gatsby tutorial on gatsbyjs.com to learn data sourcing, GraphQL and page creation step by step.

What you need before you start with Gatsby

Gatsby is a developer tool. The README assumes you are comfortable with JavaScript and React, and the official tutorial is the recommended path for people who are newer to these tools.

The README lists Node.js as the prerequisite. Gatsby is installed and run through npm, the package manager that comes with Node.js.

  • Node.js installed on your computer
  • Basic familiarity with React and JavaScript
  • A code editor of your choice

Create a new Gatsby project with npm init gatsby

Run the initializer command in your terminal. The README suggests giving the project the name "My Gatsby Site" when prompted. This creates a new directory for your site.

npm init gatsby

Start your site in develop mode

Move into the new project directory and start the development server. The README says the site will then be running at http://localhost:8000. Develop mode updates the browser in real time when you save changes.

cd my-gatsby-site/ npm run develop

Edit your first page

Open the project folder in your code editor and edit src/pages/index.js. Save the file and the browser will update. At this point you have a working Gatsby website that you can customize.

  • Main page file: src/pages/index.js
  • Local address: http://localhost:8000

Understand how Gatsby gets its data

Gatsby can load data from Markdown files, headless CMSs such as Contentful or WordPress, and REST or GraphQL APIs. Source plugins load the data, and you then work with it through Gatsby's uniform GraphQL interface.

This is the part that takes the most learning. You need to understand GraphQL and the plugin-based data pipeline before you can build content-heavy pages efficiently.

  • Use source plugins to bring in data
  • Query all sources through one GraphQL interface
  • Plugins are listed on the official Gatsby plugins page

Choose rendering options per page

Gatsby supports Static Site Generation (SSG), Deferred Static Generation (DSG), and Server-Side Rendering (SSR). You can choose the rendering option for each page, so you can mix static, deferred, and server-rendered pages in one site.

Gatsby also automates code splitting, image optimization, inlining critical styles, lazy-loading, and prefetching, according to the README.

  • SSG: static pages built ahead of time
  • DSG: deferred static generation
  • SSR: server-side rendering on a per-page basis

Deploy a Gatsby site

Gatsby sites do not require servers, so you can host the built site on a CDN. The README notes that many Gatsby sites can be hosted free on Netlify and similar services. It also describes a one-click Netlify deploy that uses the gatsby-starter-blog repository, which rebuilds and redeploys when you push changes.

What people use it for

  • Content-heavy sites such as blogs and documentation
  • E-commerce sites and user dashboards built as React apps
  • Sites that mix static, deferred, and server-rendered pages
  • Sites hosted on a CDN without running your own servers

Frequently asked questions

Is Gatsby free to use?

Yes. The README describes Gatsby as a free and open-source framework, and the repository is licensed under the MIT License. You can read the LICENSE file for the full terms.

What do I need to install Gatsby?

The README lists Node.js as the prerequisite. You then create a project with npm init gatsby and start it with npm run develop.

Is Gatsby good for beginners?

The README says the framework assumes developer skills. Beginners without React or JavaScript experience should learn those first, and the official tutorial is the recommended starting point.

Where does my Gatsby site run during development?

After you run npm run develop, the README says the site runs at http://localhost:8000 and the browser updates when you save changes.

How does Gatsby compare to Next.js, Astro, Hugo or Eleventy?

Gatsby is often compared with Next.js, Astro, Hugo and Eleventy. This page does not cover benchmarks, so check each project's documentation against your own needs, such as React use, GraphQL and data sources.

Does Gatsby need a server to host my site?

The README says Gatsby sites do not require servers and can be hosted on a CDN. Sites that use SSR per page need a server-rendering setup for those pages.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gatsby suits developers who already know React and want content-heavy sites with a shared GraphQL data layer, deployed to a CDN. If you are new to JavaScript or only need a very simple static page, a plain HTML generator or a simpler tool will likely be less work.

Install options & downloads