Your First Steps with Gatsby v2

We’ve previously explored the philosophy behind Gatsby as well as some of its major features, so it’s about time we jump in and start building websites with it. We’ll explore here how to get started with Gatsby v2.

Gatsby CLI

The very first step to get started will be to install the Gatsby CLI globally:

$ yarn global add gatsby-cli

# or, using npm:
$ npm install gatsby-cli -g

And now we can use the gatsby new utility to initiate a new project:

$ gatsby new my-site

This will create a my-site directory with the following starting file structure:

├── /.cache
├── .gitignore
├── .prettierrc
├── LICENSE
├── README.md
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── /node_modules
├── package-lock.json
├── package.json
├── /src
└── yarn.lock

Now you can cd into your new site’s directory and start working on it by running gatsby develop:

$ cd my-site
$ gatsby develop

And now you can visit your site at http://localhost:8000/:

Using a Starter

The default Gatsby starter site is used when using the gatsby new command without extra arguments, but we can also use a number of other officially supported or community starters. There currently is 3 official starters: gatsby-starter-default, gatsby-starter-hello-world and gatsby-starter-blog.

You can also have a look at the different community starters here.

Our ultimate goal starting with this post will be to build a fully-featured blog using Gatsby, so instead of using the default starter like we did in the previous step, let’s use the gatsby-starter-blog. We’ll call our blog Alligator Chronicles:

gatsby new alligator-chronicles https://github.com/gatsbyjs/gatsby-starter-blog#v2

Site Configuration

The configuration for a Gatsby site is specified in the gatsby-config.js file. Our starter already populates that file with a default config, but now we can change it up a bit:

module.exports = {
  siteMetadata: {
    title: 'Alligator Chronicles',
    description: 'The chronicles of a somewhat lonely Alligator.',
    siteUrl: 'https://alligator-chronicles.com/',
  },
  plugins: [
    ...
  ],
}

We’ve changed the site’s metadata to suit our needs and also removed the pathPrefix, which is useful only if our blog was not meant to live at the root of the domain. We’ve kept the plugin configuration the same, as this is something we’ll explore in future posts.

Adding a New Post

With the way in which the official blog starter is setup, we can add posts by creating a new directory for each post in the project’s /src/page directory and then an index.md file with the content of the post.

For example, add a new post to our site:

---
title: Lonely Gator
date: '2018-08-16'
---

I'm just a lonely gator, going about my life. **Croc croc**!

For the most part our blog posts are just simple mardown files. The only difference is the addition of some frontmatter metadata at the top of the file wrapped with — which provides data that will be available to query against using GraphQL.

Building

Later, when our blog is really to go live, we’ll make use of the gatsby build command to compile all of the assets and build the static files:

$ gatsby build

This adds the ready-to-be-deployed assets to a public directory in the root of our project. The content of that folder can simply be uploaded to a static hosting provider for our blog to be live.

Once your site is built, you can also use gatsby serve to serve the built and optimized version of your site at http://localhost:9000/:

$ gatsby serve

This can be useful to test out your site just as it will be on a live host.

Wrapping Up

Now that we’ve scratched the surface and initiated a new Gatsby site, we’ve set the stage to start digging deeper in future posts and start with the nuts and bolts of building our blog.

In the meantime, I encourage you to give a read to the official v2 documentation.