Your First Steps with Gatsby v2

Published on August 16, 2018


Your First Steps with Gatsby v2

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

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
├── 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/:

Starter Gatsby site

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.

Note that you’ll want to restart your local server after making changes to the gatsby-config.js file or creating new pages.

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.


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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel