Getting started with GatsbyJS (Part 1)

A beginners guide to building websites very easily.

Raywon Kari - Published on June 06, 2020 - 12 min read

---

Background

After a few years in the tech industry, I have learnt that, one needs to continuously learn and upskill on a daily basis, and also be willing to share the same knowledge consistently. There are many ways to learn, however I have been thinking on how I could share the knowledge in a good way and I thought writing blogs would be the best approach.

To start blogging, I narrowed it down to two options:

1. Use any of the available website builders, pick a theme and start writing => Easy learning curve, but nothing new.
2. Design and develop your own blog => Not so easy, but lot of new stuff.

Now that I had a path to walk, the next questions came up was, which option I should pursue. I am not a core developer, so my natural choice was to go for the first option.

I was influenced by wordpress from earlier experiences, therefore I was looking for cheap hosting solutions. I even bought a subscription, a domain and also a good theme builder and wasted money on these.

Soon I became so overwhelmed with the stuff I had to do, i.e., to build the blog, layout the tasks, start writing content. ( probably due to bad project management and also not managing expectations properly ) I stopped working on this project, gave up on it and went back to my routine stuff 😂 All of this happened some time during July/August 2019.

---

In Search of Gatsby

Fast forward to March 2020, when we all started remote work due to the corona pandemic, I had so much free time all of a sudden (At least 2 hours more than I usually had each working day). This project has come back to life again.

Due to this time gap in between, I had lost interest on wordpress because I felt it to be old school. Fortunately at the same time, I was participating in a project at my workplace to evaluate an online training platform which would be used by all employees to upskill as well as use it as reference.

As part of that project, I took a course on GatsbyJS and suddenly I got hooked to it because it felt so easy to build modern websites with all the core features you need, such as PWA, SEO friendly, dynamic pages and so on.

Thanks to Fortum for having me in the evaluation project, because of that I could build my personal website, as well as the blog you are reading currently, all by myself. 🎉

---

What is GatsbyJS?

In short: It is a static site generator, based on ReactJS and powered by GraphQL. One key thing to mention here is that, GatsbyJS renders all the data at build time and serves the user instead of loading the data from a server during runtime. This does not mean that, we need to build and deploy all the time we need to update our content, if we are fetching data dynamically from a different service or APIs, they can be achieved pretty smoothly as gatsby has a so many plugins using which we could basically connect to any data store or fetch data from APIs.

---

Prerequisites

Lets begin our journey to building websites using GatsbyJS. At the end of this, I hope you will also share the same opinion as I do, about how easy it is, to build modern websites using GatsbyJS.

To continue, here are the things we need:

• Mac or Linux based computer ( windows will also work, but I never tried )
• Very little knowledge on HTML and CSS.
• Definition of Javascript and how & what it is used for.
• that's it. 🎉

---

Big Picture

We will basically break it down into small chunks of tasks. The tasks are as follows:

1. Dev environment: such as IDE, required tools and stuff.
2. Foundation for our website: such as the default layout, design, what pages we need etc.
3. Connecting all dots: Creating pages.
4. Deploying the website!

By the end of this blog, we will build a sample website similar to my personal website

---

Dev Env

In this task, we will install and configure the necessary tools we need in order to get us rolling forward.

Here are the things we need:

• npm
• git
• gatsby CLI

NPM:

npm is a package manager for javascript programming language, meaning it enables the ability to download/publish packages which are developed using javascript language. It is the default package manager for the Node.js runtime.

npm is bundled and distributed together with Node.js, which means that when you install Node.js, you automatically get npm installed on your computer.

To install Node.js, head over to this page and choose the appropriate package, download and install.

Once the installation is done, you should see a similar result on your terminal when you query for its version.

# displayed versions are from the time of this writing. 
# You may see different versions
> node --version
v14.1.0

> npm --version
6.14.5

GIT:

Head over to this page for instructions on how to install git. Choose your respective OS distribution and install git.

Once the installation is done, you should see a similar result on your terminal when you query for its version.

# displayed versions are from the time of this writing. 
# You may see different versions
> git --version
git version 2.23.0

Gatsby CLI:

GatsbyJS comes with a CLI tool, which lets us create Gatsby powered websites, and run commands for developing sites. It is available to download from the npm package manager. Once you have installed npm, you can run the following command in order install gatsby CLI tool.

npm install --global gatsby-cli

Once the installation done, you should be able to run gatsby tool and see if it works. ( You will see a few short messages about data collection when you run the tool for the first time. )

Try querying its version, like this:

# displayed versions are from the time of this writing. 
# You may see different versions
> gatsby --version
Gatsby CLI version: 2.12.45

Now the fun part starts! 🎉

---

Foundation

In this section, we will go through the following aspects:

• Creating a hello world starter
• Checking out the directory structure
• Gatsby CLI commands

Hello World Starter:

Firstly we need to create a boilerplate code to give us the necessary baseline to get started. Gatsby gives us the ability to do this using the CLI. We need to run the command gatsby new <site-name> <gatsby-starter-url>. Upon running this command the CLI tool will create a folder with the necessary files and code and also a hello world starter website with some bare minimum configuration.

All GatsbyJS starter templates can be found here.

Here is an example:

gatsby new my-website https://github.com/gatsbyjs/gatsby-starter-hello-world        
# This command will create a bare minimum website
# which displays Hello World in the browser

If you do not specify a gatsby starter URL in the above command, the default starter will be used, which can be found here. For example the command gatsby new my-website will create the default starter folder and a website.

Dev Build:

The above command will create the hello world starter website in a folder named my-website. Now navigate into the directory and kick start the website as shown below:

> cd my-website
> gatsby develop

# we should see similar output after running the develop command
You can now view gatsby-starter-default in the browser.
⠀
  http://localhost:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema      
⠀
  http://localhost:8000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build

As described, head over to your browser and open localhost:8000/ and you should be able to see the hello world website similar to this one:

Exposing website in your local network:

I want to see how my website looks on a real mobile browser, so what I do is, expose the website on all ports in my laptop, and access the website using my private IP of the laptop. To do that, we need to add -H flag to the gatsby develop command as show below:

> gatsby develop -H 0.0.0.0

# now this command will show an output like this
You can now view gatsby-starter-default in the browser.
⠀
  Local:            http://localhost:8000/
  On Your Network:  http://192.168.1.137:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema       
⠀
  Local:            http://localhost:8000/___graphql
  On Your Network:  http://192.168.1.137:8000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build

Now you can use the URL with the network IP, from your mobile and test out your website. Also this command gatsby develop, it is constructing the development bundle and a dev server, using which, the pages are computed as you navigate through the website, so we might not catch all errors until we open a particular page.

Production Build:

If we want to test all the pages and functionality before deploying, we need to construct the production build and the production server. In order to do that, we need to build and serve the website in production mode. Use the following commands to do that:

> gatsby build && gatsby serve

# This commands will create the production build 
# and serve the website on port 9000
# If you want to open the website on your network
# and access from your mobile, add -H 0.0.0.0 
# similar to the dev mode

Often times, I would like to clear the local cache and public files and re-build from scratch, in order to that gatsby provides a command for it as well. run gatsby clean and this command will delete the local cache and public folders, so we don't have to delete them manually. So whenever I wanted to construct the production website, I do like this:

gatsby clean && gatsby build && gatsby serve -H 0.0.0.0

Directory Structure:

Now let's take a look at an example of the directory structure:

.
├── LICENSE
├── README.md
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── node_modules
│   └── ....
├── package-lock.json
├── package.json
├── src
│   └── components
│       └── ...
│   └── pages
│       └── index.js
└── static
    └── favicon.ico

• The files starting with gatsby- are the API config files used by the gatsby CLI to construct the website.
  • gatsby-browser.js => Here we define APIs, which lets us respond to various actions happening in a browser. More details can be found here.
  • gatsby-config.js => Here we define the site's metadata, plugins and other general configuration such as custom logging, custom rendering etc. More details can be found here.
  • gatsby-node.js => Here we define APIs which lets us use and process the data available for us using graphql such as creating dynamic pages, cross linking and so on. More details can be found here.
  • gatsby-ssr.js => Here we define APIs which lets us customise the static HTML elements when they are being rendered on the server side. More details can be found here.

• The src/ directory has the source code for our website.
  • components/ => In this directory, we define re-usable components which are used in web pages. If we for example, have a header which we want to display across all pages, we create the header as a component, and simply call that file from the components.
  • pages/ => In this directory, we define the pages and gatsby automatically constructs each file into its own page and the URL is the file name. If for example, you type localhost:8000/page-2, it will load the page-2.js file on your local machine.
  • We can define other directories such as templates, images or any other directories and any call them from pages/ or dynamic page creation using gatsby APIs as well.

CLI commands overview:

# cleans local .cache and public directories
gatsby clean

# builds local development bundle
# exposes the website on localhost:8000
gatsby develop

# builds local development bundle
# exposes the website on all interfaces and port 8000
gatsby develop -H 0.0.0.0

# creates production bundle
gatsby build

# serves production bundle on localhost:9000
gatsby serve

# serves production bundle on all interfaces and port 9000
gatsby serve -H 0.0.0.0

To avoid typing the full commands manually everytime, I have created alias commands. Here are the commands I have configured. I added them in /Users/raywonkari/.profile file on my Mac.

# -------
# Aliases
# -------

alias gd="gatsby develop -H 0.0.0.0"
alias gcd="gatsby clean && gatsby develop -H 0.0.0.0"
alias gs="gatsby build && gatsby serve -H 0.0.0.0"
alias gcs="gatsby clean && gatsby build && gatsby serve -H 0.0.0.0"

In order to keep the blog short and readable, I have split the post in two parts, and this is the end of part-1. In part-2 , I have written the remaining topics i.e., creating web pages, styling them and deploying it to Netlify. Check it out! 😄

If you have any questions/thoughts/feedback, feel free to contact me in any platform you prefer.