Written by: Geoffrey Callaghan

how to get started in Gatsby

How To Get Started In Gatsby

Getting started with Gatsby, a popular React-based static site generator, is straightforward. Here’s a step-by-step guide to help you set up your first Gatsby website:

1. Install Node.js and npm

Gatsby requires Node.js and npm (or Yarn). Download and install the latest version of Node.js from the official Node.js website.

2. Install Gatsby CLI

The Gatsby Command Line Interface (CLI) is the recommended way to create and manage Gatsby sites. Install it globally using npm:

npm install -g gatsby-cli

3. Create a New Gatsby Site

With the Gatsby CLI installed, you can create a new site using a starter template. The default starter is a good choice to begin with:

gatsby new my-gatsby-site

This command creates a new directory called my-gatsby-site with the default Gatsby starter template.

4. Navigate to Your Site Directory

Move into the new site directory:

cd my-gatsby-site

5. Start the Development Server

Gatsby includes a development server that you can use to preview your site locally. Start the server with:

gatsby develop

Open your web browser and go to http://localhost:8000 to see your site.

6. Explore the Project Structure

A typical Gatsby project includes several key directories and files:

  • src/: Contains the source code for your site, including components, pages, and styles.
  • static/: Static assets like images and fonts that will be copied directly to the final build.
  • gatsby-config.js: Configuration file for your Gatsby site.
  • gatsby-node.js: Customize and extend the default Gatsby build process.
  • gatsby-browser.js and gatsby-ssr.js: Customize Gatsby’s client-side and server-side rendering.

7. Create and Modify Pages

Gatsby automatically creates pages for React components in the src/pages directory. Create a new page by adding a new JavaScript file:

// src/pages/about.js
import React from 'react';

const AboutPage = () => (
    <h1>About Us</h1>
    <p>Welcome to the about page!</p>

export default AboutPage;

Visit http://localhost:8000/about to see your new page.

8. Add Styling

You can style your Gatsby site using various methods, such as CSS modules, styled-components, or traditional CSS files. Here’s an example using CSS modules:

  1. Create a CSS module:

    /* src/components/header.module.css */
    .header {
      background-color: rebeccapurple;
      color: white;
      padding: 1rem;
  2. Import and use the CSS module in a component:

    // src/components/header.js
    import React from 'react';
    import styles from './header.module.css';
    const Header = () => (
      <header className={styles.header}>
        <h1>Gatsby Site</h1>
    export default Header;

9. Use Plugins and Starters

Gatsby has a rich ecosystem of plugins and starters to extend functionality. To add a plugin, install it via npm and update gatsby-config.js. For example, to add gatsby-plugin-image:

npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

Then, update gatsby-config.js:

module.exports = {
  plugins: [

10. Build and Deploy Your Site

When your site is ready, you can build it for production:

gatsby build

This command generates the static files in the public directory. You can then deploy these files to a web server or a static site hosting service like Netlify, Vercel, or GitHub Pages.

Deploy to Netlify

  1. Create a Netlify Account: Sign up at Netlify.

  2. Create a New Site from Git: Connect your GitHub (or GitLab/Bitbucket) account and select the repository for your Gatsby site.

  3. Configure Build Settings: Set the build command to gatsby build and the publish directory to public.

  4. Deploy: Netlify will automatically build and deploy your site. Future changes to your repository will trigger new deployments.


By following these steps, you’ll be able to set up, customize, and deploy a Gatsby site tailored to your needs. Happy building!