Gatsby is a static site generator for React that released its first major version last month. It's a tool taht not only scaffolds projects (or websites) for you but claims that those sites are fast in performance. If you decide to use Gatsby you will be enjoying the power of latest web technologies such as React.js, Webpack, etc. There are lot of modern paradigms that Gatsby take care for its developer behind the scenes to start building and launch their project. Another cool thing about Gatsby I like is its evergrowing data plugin ecosystem that lets a developer fetch data directly into a gatsby generated application using GraphQL.
If you know nitty gritty of react, you can defintely get started with Gatsbyjs in no time by reading this tutorial. I am not asking you to be advance with React but only the familiarity of concepts. If you like to refresh your knowledge on the same or learn more about it, I recommend following links to read and me enlightened:
Enough with the introduction. Let's get started.
We will be using npm to install our first and basic tool that we need to setup any Gatsby project. You can use yarn too. In your terminal, please execute this command:
https://gist.github.com/139b0ab40f28f42001c85b551dbd6544
You might need to add sudo at the start of the command if it gives an error for permissions.
To start a new site, go to your desired project directy, a place on your system where you might be storing all the playground or applications in their initial stage and then in terminal:
https://gist.github.com/c57086109a062805e53da8cfc9e24cb8
You can name your project anything you like, I named that just for the brevity.
Once the installation and setting up of the project is done, change directory into the newly created folder and run gatsby develop from the command line to see your site running live at http://localhost:8000.
In your browser window, this how a default Gatsbyjs application looks like:
Leave the command running since it enables Hot Reloading and from now any change we make to our project will be reflected directly, without refreshing the page.
Currently, our application contains of two pages (hence, the bare minimum routing is already done for us). Before diving into code and making an amendments to that, first we need to understand the project structure such that you can make use of it by manipulating it in your future projects.
Every Gatsby project contains at least these files. You might be familiar with sum such as node_modules, public directory (which is served when deployed), and files such as package.json since it contains the meta data of any modern javascript application.
Our main focus and concern is on the directory src and file gatsby-config.js which contains meta data and other essential information of our current application.
Inside the src/ there are two sub-directories: layouts/ and pages/.
The layouts/ contain further two files: index.css and index.js` which is serves as the starting point of our application.
https://gist.github.com/188ccf181fe5c61fd9d357ca96c6edf1
The Header component contains the styles and markup that is currently serving as the header of our application. It is reflected on every page by TempplateWrapper which is our main layout component in the application. This certainly means that this component can be used for displaying navigation menu (which we are going to do in a while) or a footer.
The Link tag you are seeing is the way gatsby let our vsitors to navigate from one page to another. The react-helmet library that serves the purpose of attatching header information in HTML. It is being currently generated by the JSX. You can read about this useful, beginner friendly library on its official doc here.
Do notice the {children()} prop which is a function that exectues within the JSX code to determine the exact location for the child components to render.
Our second concerned directory pages/ contain rest of the pages that builds up our application. They are plain React components. Let's take a look at the index.js file inside this directory which currently serves as the main page of our application.
https://gist.github.com/d7632de9c0e81fbe400736dab7fc1a31
Similarly, you will find the code in page-2.js. If in our browser window, we try to navigate to the second page, notice the URL of the site when the second page loads.
It is same as the file name. We are also using Link tag from gatsby to navigate back to the homepage.
Let's add another page to our site. Inisde the pages directory create a new file page-3.js.
https://gist.github.com/463ab65d219b0d99d1107d5c01a34916
Now let's add the link of our new page to the homepage. Open index.js file:
https://gist.github.com/ae863519d170d09aaf45199a12972a23
This renders correctly on our page. Do notice the 404.js file in the direcotry. This file is rendered when no desired URL is found. More info can be read in official Gatsby docs.
Now to make things a bit more interesting, let's add a navigation menu in the Header component of our layout.
Open layouts/index.js and inside the Header component, add the following code:
https://gist.github.com/2da7c359c8c0c41e285ce1b90d12f272
If you save the file, the results of it are reflected immediately on the homepage and on every page.
https://gist.github.com/dfbefb5a09c93f1816198d9db253dd6c
The last important file of our concern is gatsby-config.js in the root folder. This file can contain site's metadata and additional information such plugins that we install using npm command but their scope of usage and concern are only with a project generated using Gatsby CLI. By default the plugin gatsby-plugin-react-helmet is installed.
A complete list of plugins are listed here.
So far we have come out with a bare minimum static site that serves the purpose of this walkthrough. Last step that I want to focus is on deployment. I will be using Github Pages for deployment.
To deploy a project on Github pages make sure your current working directory is initialised as a git repository and hosted on Github. If that is good, let us add module called gh-pages as a dev dependency.
https://gist.github.com/862dfd067d9af2c8e630cf068764aff1
Add a deployment script in package.json:
https://gist.github.com/331d37106cf7cb69cf8e20bb60dc33c0
In gatsby.config.js file add the pathname prefix of the repo such:
https://gist.github.com/1aa5cad0bb53037ecc5d252ab0d9cf82
See official docs on path prefixing.
Now from your terminal run:
https://gist.github.com/a10e35f1d050d503039373057bc70f43
Viola! You site is now live on https://username.github.io/project-name/.
I'd list some of the advantages Gatsby hold in its shield:
- HTML code is generate server side
- Easily extensible by plugin ecosystem
- Pre-configured Webpack-based build system (no need to break your head)
- Optimized for speed. Gatsby loads only critical parts so that your site loads as fast as possible. Once loaded, Gatsby prefetches resources for other pages so that clicking around the site feels incredible fast.
- Automatic routing based on your directory structure. (no need for separate routing/navigation library)
You can find the complete code of this project at this Github Repo
For more questions, contact me on Twitter or read more about me at my website.
Few places gists are referenced where there is one line command. It rather makes sense to directly have the command here. Or the gist embedded. Since it avoids going to multiple links and makes it easier to maintain context.