Learning GatbyJS – Set Up & Installation

Note: This is part 1 of four-parts Learning GatsbyJs series. This learning post is still in active development and updated regularly.

The popular content management systems (CMS) like WordPress, Drupal & Joomla are hugely popular open source software to author & manage website contents. WordPress is used by 34.0% (CMS market share of 60.8%) of all the websites at the of this writing. However, CMS-based sites are considered to be slow & buggy because they are based on database & template engine where each page is assembled on-demand pulling content from server database. In addition, there is greater risk of site security.

On the other-hand, the static site generators like Jekyll, Hugo, Gatsby, NextJs and others are gaining popularity among developers because they are blazingly fast. They generate all the pages of the site at once, thus making page caching easier with better performance. Most important advantages of SSG-based site is they are more secured.

Why Gatsby?

Learning to build React based single-page application (SPA) site has been one my 2019 learning goals. While I am little behind in my React learning, building SPA with GatsbyJS is another alternative because it is blazing fast modern site generator for React. While doing Gatsby projects, skills on react components come handy and could be further improved.

GatsbyJs is React component based framework, top-level files & directories structure of its generated sites look similar to those created with create-react-app.

Although GatsbyJs general usage statistic is less than 0.1%, it is used by many in developers community because of its no page reload, image optimization, pre-fetch resources, building minification features and other modern web features. In addition, Gatsby maintains a easy to follow documentation even to people without much web development experience. Further discussion on why Gatsby? and its advantages over other SPAs will be discussed in a separate post.

This learning post was inspired by many tutorials including useful resources (see below) and this post from Tania Rascia.


GatsbyJS is open source framework based on ReactJs. To use Gatsby, it is assumed working JS knowledge, understanding how ReactJS works, and some core web technologies (eg. HTML, CSS) and basic use of required software tools (eg, NodeJs, NPM). These topics are discussed else where in the site.

The objective of this learning series is to explore GatsbyJs to build an simple SPA blog site and document step-by-step procedures to install & setup Gatsby and overview of its building blocks.

Learning series
Part 1: Learning GatsbyJS – Setup & Installation (this post)
Part 2: Understanding GatsbyJS Building Blocks
Part 3: An Overview of Gatsby Plugins & GraphQL
Part 4: Learning to Programmatically Create Pages in Gatsby

In this part 1 of the four-parts series, step-by-step procedures to install & set a basic starter Gatsby site & overview its file structures are briefly discussed.

Set Up & Installation

Install Homebrew

Install Homebrew package manager, if it is not already installed in your machine. To check if homebrew is installed, issue the following command:

$ brew -v
#! if installed
Homebrew 2.1.4 

#! if not installed
-bash: brew: command not found 

In MacOS Homebrew allow to install an app from the command line. If not install, download & install Home-brew with the instructions for MacOS:

#! paste the following command
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/

In older MacOS versions, the XCode installation is required to install Homebrew. In recent versions (eg. Sierra, Mojave) it is no longer necessary, if not already installed it will also be installed.

NodeJS and NPM

Check if Node.js and NMP (node package manager) is installed in your machine. If it is not installed, download & install.

#! check node -- version
node --version
V10.12.0 #! output if installed
#! check npm version
npm --version
6.9.0  #! output if installed
#! to upgrade npm to latest version
npm install npm@latest -g

Because GatsbyJS is ReactJS based, it requires latest JS features with Node >= 6 and npm >= 5.2 on the machine. Set up and installation of Node.js & NMP and updating to latest version is discussed in React App Development Setup on MacOs.

Addition Resource: NPM installation | Node.js fundamentals: how to upgrade the Node.js version

VS Code for GatsbyJs Development

The popular VS Code text editor is a great choice for GatsbyJs development too just like ReactJS development. If VS Code is not already installed in your machine, download & install from VS Code official site in your machine.

Lunch ‘Integrated Command Line’

Lunch VS code integrated terminal through view > integrated terminal. If VS Code has been installed with ‘code’ command in PATH in your machine, shell command can be issued from any selected folder.

GatsbyJs documentation recommends installation of VS code Prettier plugin for code formatting & avoiding errors. Download & install Prettier VS Code plugin, from VS Code: view > extensions, search for “Prettier – Code formatter” and click > Install. Set up & installation of VS Code is also described briefly in React development post too.

Getting Started with Gatsby

1. Install Gatsby CLI

To quote from Gatsby documentationGatsby CLI allows quickly create new Gatsby-powered sites and run commands for developing Gatsby sites. It is a published npm package.” Gatsby CLI is installed globally using npm or yarn as shown below:

#! using nom
npm install -g gatsby-cli
#! using yarn
yarn global add gatsby-cli

Other available Gatsby commands can be viewed by running gatsby --help command from the terminal.

Git installation: The GatsbyJS documents recommends to install Git to handle your projects. This step will also allows to set up and lunch a Gatsby site at GitHub at no cost (free). Follow these steps to download & install Git on macOS.

2. Create Project Directory

A project directory folder named gatsby-projects was created through integrated command terminal as shown below:

#! create project folder
cd Documents
#! make gatsby-projects folder
mkdir gatsby-projects
#! change directory to gatsby-projects
cd gatsby-projects
3. Create Gatsby Sites in Project Folder

Create a desired project folder (eg. gatsby-projects). For learning and  illustration purposes, lets install both the default and blog starter kits in the project folder.

From the project folder create a project named my-gatsby-site using the default starter template:

#! create a new Gatsby site using the default starter
gatsby new my-gatsby-site https://github.com/gatsbyjs/gatsby-starter-default

To install Gatsby blog starter kit & create a new Gatsby site in project named my-gatsby-blog using default blog starter template, run the following command from the command line:

#! create a new Gatsby site using the blog starter
gatsby new my-gatsby-blog https://github.com/gatsbyjs/gatsby-starter-blog

Next navigate into project folder & start developing.

4. Start Local Development server

To start the development server, change to project folder (eg. my-gatsby-blog) and run gatsby develop command as shown below:

#! navigate into new site directory
cd my-gatsby-blog
#! start development server
gatsby develop

If no errors displayed, the new Gatsby site is developed in your local server and is available to view and interact locally at http://localhost:8000/.

Figure: Screenshot of successful compilation of Gatsby develop in the local server.
5. View Site Locally

To view the new Gastby site, navigate http://localhost:8000 in a new browser tab and the following screen will appear.

Figure: Screenshot of default Gatsby starter blog site successfully developed in local server.
6. Stop/Start Development Server

To stop the development server, from terminal window issue <strong>control+C</strong> command. To re-start or start, issue gatsby develop again.

An  Overview of GatsbyJs File Structure

The top level files & directories of Gatsby’s starter default as shown in the project folder:
├── node_modules
├── src
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── package-lock.json
├── package.json
└── README.md

The file& directory structure of Gatsby starter blog default is also similar except it contains two additional folders: content & static, as shown below:
├── content
├── node_modules
├── src
├── static
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── package-lock.json
├── package.json
└── README.md

A brief description of files & directories as described in Gatsby’s starter default & starter blog:

/content: contains assets and all of the blog posts.

/static: contains the static files (eg. icon and robots.txt).

/node_modules: contains all of the modules of code that your project depends on (npm packages) are automatically installed.

/src: contains all of the code related to the site (eg. site header or a page template). src is a convention for “source code”.

.gitignore: This file tells git which files it should not track / not maintain a version history for.

gatsby-browser.js: This file is where Gatsby expects to find any usage of the Gatsby browser APIs (if any).

gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc.

gatsby-node.js: This file is where Gatsby expects to find any usage of the Gatsby Node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.

gatsby-ssr.js: This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs (if any). These allow customization of default Gatsby settings affecting server-side rendering.

LICENSE: Gatsby is licensed under the MIT license.

package-lock.json. This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (Don’t change this file directly).

package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.

README.md: contains useful reference information about your project.

Source: Gatsby Starter default & blog.

Next Step

Now, that basic GatsbyJs site development environment is setup, next step to is to getting familiar with Gatsby building blocks and their basic manipulation.

Wrapping Up

In this part 1 of the four-parts GatsbyJs learning series, step-by-step procedures to install GatsbyJs starter default sites using Gatsby CLI (a npm package) were discussed. In the part 2 & 3 of this series, manipulating pages & understanding Gatsby data will be discussed.

Next Post: Understanding GatsbyJS Building Blocks

Useful Resources

While preparing this post, I have referred the following references extensively. Please to refer original posts for more detailed information.