The GatsbyJS Folder & File Structure – A Quick & Simple Walkthrough

Tapha Ngum

Published: 2021-08-6

Gatsby File StructureGatsby Folder StructureGatsbyJS

As with any program, the core elements of a Gatsby site come down to the key folders and files that together make it up.

Below we will show the basic folder structure of a typical Gatsby project:

Many of the folders shown here typically come with Gatsby installation, but we are going to focus here on only the folders and files that are necessary to formulate a full Gatsby site.

These are (in order of importance):

package.json & package-lock.json

The NPM Files

If you’re familiar with the node js/npm ecosystem then you’ve likely come across these before. Essentially they are the files that tell node which packages to grab and install from the node package manager, ‘npm’. Package.json is the file where the files to be installed are specified. Package-lock.json keeps track of what has already been installed.

The installed packages are kept in a directory called /node_modules, which you’ll see in your folder directory but don’t need to worry about because you shouldn’t edit it directly.

Gatsby CLI and gatsby itself will be installed using this system from NPM.

These files also allow us to specify how we want our scripts to run and compile our code. Specifically the package.json file.

gatsby-config.js

Gatsby’s Configuration File

gatsby-config.js is the file where we add the configuration options for our Gatbsy site. It is here that you add your site name and description, your Gatsby plugins, and their settings, etc.

gatsby.node.js

Gatsby’s custom pages configuration file (Important for creating our blog pages!)

This file is the one we will be using to create our custom pages (such as blog posts). They can be used for any kind of custom pages that you’d want to create on your Gatsby site. It works by allowing you to hook into the Gatsby API when Gatsby is ‘building’ your site and add in the pages and data that you want to add in. Which is how we add blog pages to our Gatsby site.

src

This folder essentially contains our main views for our Gatsby site. The front end pages that our users will see and interact with. We will cover the subfolders within this folder step by step below.

src/components

In this folder, you have your basic layout files that contain the templates that typically get included within every page, such as your overall ‘Layout.js’ file, your ‘Header.js’ file, which contains your top of page ‘<head>’ html and maybe your navbar, etc.

These are structured as React components. And are translated to your page HTML by the Gatsby core API as such when ‘building’.

src/pages

Here now you have all the main pages of your site, including your initial index.js page. This is the page that users land on when they land on the homepage of your site. You also have all your other pages referenced here, such as your ‘about-us.js’ page and your ‘contact.js’ page.

These are also structured as components by Gatsby’s API that at build time are translated to be your HTML pages.

Side Note: Page Routing – And How It Works

Gatsby core automatically turns the pages in src/pages (which are structured in the form of React components) into your final output HTML pages. For example, your ‘about-us.js’ would be accessible via ‘yoursite.com/about-us’.

src/images

Here we store our image files that we will reference within our pages, components and templates. These files are automatically optimized and minimized at ‘build’ time for faster site performance.

And finally…

public/

This is where our built files live. Once we have run our build scripts, this is the path where the files that will ultimately be served and seen by our users end up.

These all together make up what we know of as the recipe known as GatsbyJS.

Check out the easiest way to plan your website or mobile app. Try PlanFlow for free.