Learn Gatsby - Starting a Gatsby Project

#Introduction

The theory from episode 2 is enough for now. Time to write real code: creating your first Gatsby project. By the end of this episode you'll have a Gatsby site running in the browser with live reload.

Episode 3 covers creating a project with the Gatsby CLI, exploring the folder structure, running the dev server, and adding basic plugins along with their configuration in gatsby-config.js.

#Creating a Project with the Gatsby CLI

#Using an Official Starter

The Gatsby CLI provides the gatsby new command to create a project from a starter. A starter is a ready-to-use Gatsby project you can use as a starting point:

npx gatsby new gatsby-belajar https://github.com/gatsbyjs/gatsby-starter-hello-world

The command npx gatsby new gatsby-belajar clones the starter, installs all dependencies, and sets up git. Wait for the success message, then enter the project folder:

cd gatsby-belajar

#Available Starters

Besides hello-world, Gatsby provides several official starters: gatsby-starter-default for a complete site, gatsby-starter-blog for a blog with Markdown, and gatsby-starter-wordpress for WordPress integration. For learning purposes, the hello-world starter is the simplest and cleanest.

#Exploring the Initial Structure and Configuration

#Project Contents

Take a look at what the new project contains:

ls -la

The hello-world starter is very minimal: the src/pages folder, gatsby-config.js, package.json, and a few supporting files. The file src/pages/index.js is your first page — when run, this file becomes the / route.

#Reading gatsby-config.js

The main configuration lives in gatsby-config.js. Open it and you'll see a structure like this:

Minimal gatsby-config.js

module.exports = {
  siteMetadata: {
    title: "Gatsby Belajar",
    description: "Situs belajar Gatsby",
  },
  plugins: [],
}

The siteMetadata property stores global site information that can be queried via GraphQL, while plugins is an empty array that we'll fill in later.

#Running the Dev Server and Live Reload

#The Develop Command

Run the dev server from inside the project folder:

npm run develop

This command runs gatsby develop behind the scenes. When it's done, open http://localhost:8000 in your browser. You'll see the starter's hello-world page.

#Live Reload and GraphiQL

Change the text in src/pages/index.js, save, and the browser will update automatically without a manual reload — that's live reload. At the same time, Gatsby runs GraphiQL at http://localhost:8000/___graphql, an interactive explorer for trying out queries before writing them in code.

#Stopping and Restarting

To stop the dev server, press Ctrl+C in the terminal. The npm run develop command can always be run again to resume development.

#Adding Basic Plugins

#Installing the Filesystem Source Plugin

The first plugin you'll almost always need is gatsby-source-filesystem, which lets Gatsby read local files like Markdown and images:

npm install gatsby-source-filesystem

#Configuring the Plugin

To activate it, the plugin must be registered in gatsby-config.js together with its options:

Register the plugin in gatsby-config

module.exports = {
  siteMetadata: {
    title: "Gatsby Belajar",
    description: "Situs belajar Gatsby",
  },
  plugins: [
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "content",
        path: `${__dirname}/content`,
      },
    },
  ],
}

The path option with the value ${__dirname}/content determines the folder that gets scanned. After adding the plugin, Gatsby needs to be restarted with npm run develop so the graph gets updated. The content folder doesn't exist yet — create it with:

mkdir content

#Initial Verification

To make sure everything is working, run a query in GraphiQL to see the file data you just sourced:

Query files in GraphiQL

query {
  allFile {
    nodes {
      name
      extension
    }
  }
}

If allFile returns nodes, the plugin configuration worked. From here you're ready to build a more complete site structure in episode 4.

#Conclusion

Episode 3 completed the first hands-on step: creating a Gatsby project from a starter, understanding gatsby-config.js, running the dev server with live reload, and adding and configuring the gatsby-source-filesystem plugin.

Key takeaways:

• npx gatsby new nama-project creates a project from a starter.
• src/pages automatically defines your site's routes.
• npm run develop runs the dev server on port 8000.
• GraphiQL at ___graphql is for trying out queries.
• Plugins are registered in the plugins array in gatsby-config.js.
• Every time you add a plugin, restart the dev server so the graph updates.

In the next episode we'll build the visual foundation: pages, components, and layouts — creating new pages, separating reusable components, choosing a styling strategy, and managing page metadata with the Gatsby Head API.