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?
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.
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.
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
(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_website_starter
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:
- Blog (written with markdown)
- RSS feed at
- 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
localhost:8000 in your browser to view the site.
As you edit the site, the page will automatically reload with the changes.
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
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).
To link to another page on the Gatsby site, use syntax like this:
<Link to="/about/">About Page</Link>
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
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.
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.
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.
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
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
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.