How to Create Gatsby Sites - Beginner Tutorial

How to Create Gatsby Sites: A Beginner’s Guide

GatsbyJS is a powerful static site generator built on React (Official site), known for creating blazing fast websites with great developer experience. This tutorial walks you through creating your first Gatsby site — from tooling setup, site creation, adding content, to deployment.

Prerequisites

Basic understanding of HTML, CSS, and JavaScript, especially React.
Node.js and npm installed on your system. You can download them from the Node.js website (Official site).
A code editor like Visual Studio Code or your favorite IDE.
Basic command line knowledge to run commands.
Git installed, if you want to version control your site.

Step 1: Install Gatsby CLI

Gatsby CLI helps scaffold projects quickly. Open your terminal and run:

npm install -g gatsby-cli

Check installation by running:

gatsby --version

Step 2: Create a New Gatsby Site

Use Gatsby CLI to create a new project with a starter template:

gatsby new my-gatsby-site

This command downloads the default starter and sets up the project folder my-gatsby-site.

Step 3: Start Development Server

Navigate into your project folder:

cd my-gatsby-site

Start the Gatsby development server:

gatsby develop

Open your browser at http://localhost:8000 to see your Gatsby site live locally. Hot reloading lets you see changes instantly.

Step 4: Explore Project Structure

/src/pages: Put React.js components here to create pages (each file is automatically a route).
/src/components: Reusable parts you want to use throughout the site.
gatsby-config.js: Configuration file for plugins, site metadata, etc.

Step 5: Add Your Content

To add a new page, create a React component inside src/pages. For example, create about.js:

import React from 'react';

const AboutPage = () => (
  <div>
    <h1>About Us</h1>
    <p>Welcome to our Gatsby site!</p>
  </div>
);

export default AboutPage;

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

Step 6: Use Plugins to Extend Functionality

Gatsby’s ecosystem has many plugins for images, Markdown, SEO, sourcing data from CMSs, and more.

To install and use a plugin, first add it as a dependency. For example, to add Markdown support:

npm install gatsby-transformer-remark gatsby-source-filesystem

Then configure in gatsby-config.js:

module.exports = {
  plugins: [
    `gatsby-transformer-remark`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `pages`,
        path: `${__dirname}/src/pages/`,
      },
    },
  ],
};

Step 7: Build and Deploy

Once your site is ready, build static files for production with:

gatsby build

This generates optimized static files in the public folder.

You can deploy these files to any static hosting service like Netlify (Official site), Vercel (Official site), or GitHub Pages.

Troubleshooting Tips

Build errors: Make sure Node.js is up-to-date and you installed all plugins correctly.
Port conflicts: If gatsby develop tells you port 8000 is in use, specify another port with gatsby develop -p 9000.
Slow builds: Optimize images and minimize unnecessary plugins to improve build speed.