Creating A New Gatsby Site

child at the bottom of the stairs

Before we get going with this post if you have not read my previous post on Gatsby. Please, take a couple of minutes to get caught up. The post can be found here The goal of this post is to create a new Gatsby site, but we have to do some setup before we can get started inspecting a solution, time to install some tooling. These tools are quite similar to other JavaScript frameworks to create the project and some other handy tooling to ease in development. The first thing that is needed is Node.js, if you don't have this installed already the best bet is to install the latest long-term support version (LTS). The newest version of the runtime is a fine option as well, I have seen on other projects that some dependencies may break with selecting the latest versions.

With node installed it's time to install the Gatsby Command Line Interface (CLI). This is quite a quick installation. Open your favorite command prompt and execute npm install -g gatsby-cli. In this command, we are telling Node Package Manager (NPM) to install the gatsby-cli package. the -g flag is instructing NPM to install the package globally, meaning it is available in any/all directories on the filesystem. With both these installed you should be able to execute gatsby --version and see an output containing the version of the Gatsby CLI installed. With this, all the development tooling we need to continue is installed.

Now we can create the shell of our Gatsby solution. Choose a suitable directory to contain the new website and navigate there using your favorite command prompt. Next, execute the command gatsby new. The CLI will then ask you a series of questions:

  • What would you like to call your site?
  • What would you like to name the folder where your site will be created?
  • Will you be using a CMS?
  • Will you like to install a styling system?
  • Would you like to install additional features with other plugins?

In your installation, answer each question to your liking. The only addition I have added is Sass as a styling system. Once the questions have been answered, you will see several logs fly by as the Gatsby CLI pulls down templates and configures a solution for you. After the installation is completed, you can move the command prompt working directory to the new folder that was created. Then execute the command gatsby develop. After a build action executes a browser should open to localhost:8000 and you should see the default Gatsby site. How exciting, we now have a solution to build upon. If you are using source control, shame on you if you are not, now is a great time to check it in and push it to your remotes.

Let's take a quick look at what just was installed in this new directory. The first item of interest gatsby-config.js this is the file that Gatsby uses to contain configuration for your site. Within the file there is a siteMetadata object, this is a container used to set the global values that would be used throughout the site. Next is a property plugins which is used to contain configuration for all the additions we choose to add to our site. As you will see in a later post, there are several hundred plugins to choose from. Or you can create your own. On to the src directory. There are 2 child directories images and pages. We will skip images as there is nothing special there. The other directory, pages, is very interesting. This is a special directory within the Gatsby ecosystem. Any *.js files in this directory will translate to a page in the site structure in the hosted directory. If you are to open the index.js file, you will find what appears to be a basic React component.

Next up, we will customize the site and get a further understanding of Gatsby tooling.