Update: this tutorial is probably outdated. See the official Gatsby quickstart for current information.
This is a quick tutorial about how to quickly build and deploy sites using GatsbyJS. It’s designed for people who know at least a little React and want to try Gatsby.
The starter template I made could be used as a base for a portfolio website and includes a blog feature. It should be pretty easy to edit the design, and add new content types and other features.
What Is Gatsby?
React is a JavaScript library. There are several tools out there to help with creating React sites. Three of the common ones are:
- create-react-app
- Next.js
- Gatsby
Each tool creates a different kind of React site.
This tutorial covers Gatsby, which I think is the best everyday method for creating a content-heavy site in React.
(Tip: Vue has the same kinds of tools: vue-cli, Nuxt, and Gridsome. I’m planning to write some Vue tutorials soon.)
Example sites that use Gatsby include: the official React JS site, National Geographic, DigitalOcean, TypeScript, and Figma.
Why Gatsby?
Single-page applications (SPAs) generally aren’t good for content-heavy websites. Sometimes they can be indexed by search engines, but even when they are, they don’t rank as well. If people can’t find your site by searching for it, it won’t get as much traffic.
Frameworks like Gatsby (also Next, Nuxt, and Gridsome) solve that problem by rendering the output as HTML files on the server. Search engines can then read the content just like they could from any regular HTML file. But after the first page load, the sites become SPAs, with all of the speed benefits of SPAs.
Also, the server-rendered JavaScript frameworks still allow you to easily add dynamic frontend code on top of the HTML pages in almost the same ways as writing typical SPA code.
So with Gatsby, you get most of what you get from create-react-app but also better search engine traffic and additional features.
How to Install Gatsby
If you don’t already have Node.js installed check out this page: [Tutorial] How to Install Node.js on Linux, Mac, and Windows
After Node.js is installed, install Gatbsy by running this command in a terminal:
$ GATSBY_TELEMETRY_DISABLED=1 npm install -g gatsby-cli
After it installs, permanently disable the telemetry with:
$ gatsby telemetry --disable
UPDATE: Gatsby 3 lets you start new Gatsy sites like this:
$ npm init gatsby
Then answer a few questions about the features you want.
My Gatsby starter still works, but you can also use the init command and then use my starter for ideas. See the comments below for more discussion about it.
(I think that development tools and NPM packages shouldn’t be sending unknown data to remote servers.)
Starting a Gatsby Project
Run this command to start a new Gatsby site using my starter template, changing “project_name” to the actual name of your site:
$ gatsby new project_name https://github.com/j127/gatsby-starter-website-blog
There are many starter templates to choose from. The one I’ve created helps you get a site online faster, because many things are already configured for you. If you use the built-in starter instead of my template, it will take longer to build something, because you’ll have to learn how to wire up the GraphQL with some content source before you can build something.
You’ll still need to learn the GraphQL part later, but I think it’s motivating to have a site online, so I’d recommend putting a site into production before worrying about learning every detail of the framework first.
The starter template has these features:
- Pages
- Blog (written with markdown)
- RSS feed at
/rss.xml - Syntax highlighting in blog posts
- SCSS support
- Bulma CSS framework (you can easily replace it with Bootstrap or whatever you want)
- Easy deployment to Netlify
- and more
I also tried to include some examples of common tasks, like how to make a grid with Bulma. If you get stuck thinking things like, “I need to figure out how to make a grid in Bulma”, you can use a search engine to find this page, or just look at the example in the src/pages/index.js file in the starter template. 
<!-- I used Bulma, because it's this easy. -->
<div className="columns">
<div className="column">Column 1</div>
<div className="column">Column 2</div>
<div className="column">Column 3</div>
</div>
Starting the Development Server
After running the setup commands, cd into the project directory and run this command to start the development server:
$ npm start
Then visit localhost:8000 in your browser to view the site.
As you edit the site, the page will automatically reload with the changes.
Quick Tour
If you’ve used create-react-app before, the structure should appear familiar:
$ tree -d -I node_modules
.
├── content
│ ├── assets
│ └── blog
│ ├── another-post
│ └── first-post
├── src
│ ├── components
│ │ ├── footer
│ │ ├── layout
│ │ ├── navbar
│ │ └── seo
│ ├── images
│ ├── pages
│ ├── styles
│ └── templates
└── static
Pages
Any React component that you put into the src/pages directory will become a path on the site. For example, the file src/pages/about.js will be viewable at localhost:8000/about/ (note the trailing slash).
Links
To link to another page on the Gatsby site, use syntax like this:
<Link to="/about/">About Page</Link>
A Link element will tell Gatbsy to preload the target page as soon as the mouse hovers over it, making the page load almost instantly.
For external links, use regular <a> elements.
Blog Posts
If you want a blog, put your blog posts in the content/blog directory. Use the same structure as the two sample blog posts. Any images that you put in a blog post directory will be included in the final output.
Other Content Types
If you want other content types (something other than pages and blog posts), check out the section of the docs on source plugins.
Static Files
Put any extra static files into the static directory. For example, the robots.txt file is at static/robots.txt and will appear in the final build at example.com/robots.txt. It gets copied to the final build but doesn’t need to be processed on the way.
Styles
To edit the styles, check out the Bulma docs. SCSS support is already enabled — just name the files with a .scss extension. Whenever I want to do something with Bulma, like figure out the styling for navbars, I’ll just type “bulma navbar” into Google and end up in the docs.
Bulma has a lot of SCSS variables that you can override. You can change their values in the src/styles/_variables.scss file and Bulma should update.
The included template uses PurgeCSS to strip out all unused CSS styles, so the final build is small. Out of the box it should remove about 95% of Bulma’s CSS weight.
GraphQL
To understand how the GraphQL queries work, check out the running queries with GraphQL section of the docs.
Basically you can visit localhost:8000/__graphiql to see a GraphQL explorer where you can see what data sources Gatsby knows about. Point-and-click until you construct the correct query. Then run the query to fetch the data. The docs above show how to use the returned JSON in your code.
In this screenshot, the query is fetching data from the file gatsby-config.js file. You can query files, databases, APIs, the filesystem, or just about anything else, using the same syntax.
Looking Things Up
If you don’t know how to do something while working on the site, go to the Gatsby docs and look it up. If you need a feature, check the plugin directory to see if a plugin already exists.
Also, feel free to post questions below or send me a message in the chatroom.
Deploying the Site
After you edit the site and add features (similar to how create-react-app sites are built) you can deploy it to production on Netlify (free).
First build the site:
$ npm run build
The built website files will appear in a directory named public.
Then deploy it to Netlify using the tutorial here: Netlify CLI Quickstart
Your site will then be online.
I’ve intentionally kept this page short and simple so that people can follow a few instructions and get a site online instead of spending hours on longer tutorials.1.
If that was too much information for a first introduction to Gatsby, try going through the slower official tutorial and then come back here and use this template for your second site. To learn a technology, it’s good to build many things with it repeatedly, until the basic tasks are in muscle memory.
If you have questions, leave a comment below.
Footnotes
1 For longer, free tutorials, see this, this, and this and/or search this forum for “gatsby”.
