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.
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.
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.
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.
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
$ brew -v #! OUTPUT #! if installed Homebrew 2.1.4 #! if not installed -bash: brew: command not found
#! paste the following command /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/ install/master/install)"
NodeJS and NPM
#! 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 documentation “Gatsby 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
#! 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
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.
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:
The file& directory structure of Gatsby starter blog default is also similar except it contains two additional folders:
static, as shown below:
/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.
Now, that basic GatsbyJs site development environment is setup, next step to is to getting familiar with Gatsby building blocks and their basic manipulation.
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
While preparing this post, I have referred the following references extensively. Please to refer original posts for more detailed information.