So you've heard about Gatsby and you want to find out what it's all about. If you're like me, maybe you heard about Gatsby on the excellent podcast - Syntax. Or maybe all your friends have been using it and you just want to get in on the action. Either way, if you are reading this blog I will assume you have very little or no knowledge of Gatsby, because that is who this tutorial is aimed at. If reading documentation is a productive way for you to learn then I would recommend you stop reading this blog now and head straight on over to the official Gatsby Docs. There you will find an excellent tutorial that walks you through setting up your first site step-by-step. But I wanted to offer an alternative in case you are just looking for a quick overview on how to get up and running. So without further ado, lets get started.
Note: If you just want to see the steps required to get a site started then scroll to the bottom of this article, otherwise continue reading.
I will assume that you have previously installed Node, git, and npm on your machine. If you're interested in learning Gatsby then I doubt you've made it this far without having all 3 of these installed. Something you will need to install now is the Gatsby CLI which you can get by running:
npm install -g gatsby-cli.
Once you have installed the Gatsby CLI just head to the folder you want to create your project in and open up the terminal there. Run this command:
gatsby new tutorial-name
In this command 'tutorial-name' is the name of your project and can be substituted for whatever you want. Now run this command:
That's it, your site is official up and running. Navigate to localhost:8000 in your browser and you should see the starter template website.
At this point you can navigate between the two pages Gatsby has created for you to see just how fast a Gatsby site is. So how do we start editing this site to make it your own? To keep things simple lets just focus on the src folder for now. Within the src folder you will see a folder named pages. If you create a .js file within the pages folder then Gatsby will automatically generate a page on the website for you. For example, if you create a file named hello.js and then navigate to localhost:8000/hello you will see the page you just created. Of course, the file will need some content first before you can see anything on the page.
If you are familiar with React then each 'page' file that Gatsby has generated for you should look fairly familiar. Gatsby uses the same JSX syntax as React, views are rendered on the page from a function. If the existing pages don't look familiar to you then I suggest you create a new file under the pages folder, and copy/paste all of the code from the index.js file into your new file. Now start editing pieces of code and watch what happens on the page. Gatsby uses a form of hot reloading which means that any change you make to the file should instantly be visible on the site without the need to reload.
I believe that you learn best from trial and error, so I am not going to walk you through exact steps of editing files/pages. I will leave you with one more piece of advice. Navigate to the components folder and you will see a file called Layout.js - this file handles the code for elements of the site that will be consistent across all pages. For example, your header and footer will go in here. In order to use this layout component you must import it into the pages files that you are using. At the top of each page file you need to include this line:
import Layout from "../components/layout"
Then you must wrap all of the JSX code with the Layout component. Here is an example:
<Layout> <h1>This is my new page</h1> <p>I have wrapped this content with the layout component</p> </Layout>
- Install Node, NPM, GIT, Gatsby CLI
- Open folder where you want project to be stored
- In the command line run: gatsby new name-of-project
- In the command line run: cd name-of-project
- In the command line run: gatsby develop
- Navigate to localhost:8000 in your browser
- Start coding!