Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Gatsby Project Structure

Tour a Gatsby 5 project: src/pages, src/components, static, gatsby-config, gatsby-node, gatsby-browser, gatsby-ssr, and the .cache and public build folders.

A fresh Gatsby project has a handful of folders and four special files with the prefix gatsby-. Once you know what each one is for, you always know where a change belongs. This lesson is a map of the whole project, and it points to the later lessons that explore each part in depth.

The overall layout

TEXT
my-site/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ pages/          <- every file here becomes a route
โ”‚   โ”œโ”€โ”€ components/     <- shared React components
โ”‚   โ”œโ”€โ”€ templates/      <- page templates for generated pages
โ”‚   โ””โ”€โ”€ images/         <- images processed by Gatsby
โ”œโ”€โ”€ static/             <- files copied as-is to the site root
โ”œโ”€โ”€ gatsby-config.js    <- site metadata and plugins
โ”œโ”€โ”€ gatsby-node.js      <- build-time Node APIs
โ”œโ”€โ”€ gatsby-browser.js   <- browser APIs
โ”œโ”€โ”€ gatsby-ssr.js       <- server-side rendering APIs
โ”œโ”€โ”€ package.json
โ”œโ”€โ”€ .cache/             <- internal cache (generated, ignored by Git)
โ””โ”€โ”€ public/             <- the built site (generated, ignored by Git)

Only src/pages and gatsby-config.js are truly required by Gatsby's conventions. The other folders (components, templates, images) are conventions you may rename.

src/pages

Every .js, .jsx, .ts or .tsx file in src/pages that default-exports a React component becomes a page. src/pages/about.js is /about/; src/pages/index.js is /. A file 404.js becomes the not-found page. Details are in Pages and file system routing.

src/components, src/templates, src/images

  • components hold reusable pieces like a header, a card or a layout. They do not create routes.
  • templates hold components used by pages you create programmatically, such as one component for every blog post.
  • images are imported or queried so Gatsby can resize and optimize them (see the Images chapter).

Keeping route-making files (pages) separate from helper files is the reason components lives outside pages: anything inside pages turns into a URL.

static

Files in static/ are copied unchanged into public/. Use it for robots.txt, favicons, downloadable PDFs and anything that must keep its exact URL. A file static/robots.txt is served at /robots.txt. Static files are not optimized or hashed, so prefer imports for images.

The four gatsby-* files

File Runs in Typical use
gatsby-config.js Node, at startup siteMetadata, plugins, path prefix, trailing slash policy
gatsby-node.js Node, during the build create pages, add fields to nodes, customize the schema
gatsby-browser.js The browser global CSS import, route-change hooks, wrapping the app
gatsby-ssr.js Node, while rendering HTML inject scripts, match browser wrappers on the server

A minimal real gatsby-config.js:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
module.exports = {
  siteMetadata: {
    title: "My Site",
    siteUrl: "https://example.com",
  },
  plugins: ["gatsby-plugin-image", "gatsby-plugin-sharp"],
}

A minimal gatsby-browser.js that loads global styles:

JavaScript
// gatsby-browser.js (real Gatsby, read-only)
import "./src/styles/global.css"

export const onRouteUpdate = ({ location }) => {
  console.log("Navigated to", location.pathname)
}

Details on the config and node files are in gatsby-config and Node APIs.

.cache and public

Both are created by Gatsby and should be in .gitignore:

  • .cache/ stores Gatsby's data store, compiled templates and incremental build state. Deleting it is safe; the next run rebuilds it.
  • public/ is the finished website. After gatsby build, deploy the contents of public.
flowchart TD
  S["src/ and static/"] --> B["gatsby build"]
  C["gatsby-config.js<br/>gatsby-node.js"] --> B
  B --> K[".cache/<br/>internal state"]
  B --> P["public/<br/>deployable site"]

Sources go in; .cache and public are generated output you never edit by hand.

Stand-in: classify the files in a project

The following stand-in is not Gatsby. It classifies file paths the way you would read a project tree: which ones create routes, which are config and which are generated.

JS Stand-in: what is this file for?

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

No output.

Stand-in: the special files as lifecycle phases

Different files run at different moments. The stand-in lists them in the order Gatsby touches them.

JS Stand-in: which file runs when

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

No output.

Never put secrets in siteMetadata or in code that runs in the browser. Anything in gatsby-browser.js, in components, or in siteMetadata can end up in the published JavaScript. Use environment variables read in gatsby-node.js or in server functions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do files go that must be served at an exact URL, such as robots.txt?

    Everything in static/ is copied unchanged into the site root.
  2. 2. Which file runs only in the browser?

    gatsby-browser.js implements browser APIs such as onRouteUpdate and wrapRootElement.
  3. 3. Why is components kept outside src/pages?

    Each page-like file in src/pages creates a URL, so helpers belong elsewhere.
  4. 4. Which folder do you deploy to a static host?

    gatsby build writes the finished site to public/.

Summary

  • src/pages creates routes; components, templates and images are conventions.
  • static/ is copied as-is; imported assets are processed.
  • gatsby-config, gatsby-node, gatsby-browser, gatsby-ssr each run at a different time.
  • .cache and public are generated and ignored by Git; deploy public.
  • Never store secrets where browser code or siteMetadata can expose them.

Next: The Gatsby CLI and Dev Server