How I Made This Blog

This blog was made with Gatsby.js. Over all it has been a blast to make and the fact that I could reuse my react skills made me feel like I am in control.

There were however some things that took some time to sink in. So I though it might be nice to create a post about the concepts that were hard for me to grasp.

I started out this blog post thinking it would be more or less a step by step guide of how the Blog was made. But to be fair there are a lot of these guides out there and most of them are brilliantly written. So if you are looking for a step by step guide I would much rather refer you to those:

Initial Starter Pack

So one of the tings I wish that I had done differently was to start out with the hello world starter pack instead of the default one.

There are a lot of nice things in the default started pack like SEO, Manifest and all of that goodness. But before I understood how gatsby works, this initial stuff became rather confusing.

Therefore I strongly recommend anyone who wants to learn Gatsby.js to initialize a project with:

gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world

This is also what they recommend in the official tutorial so maybe I should have read that he he.

What It Actually Does

So gatsby is a static page generator. It took some time for me to realize what is actually meant. I thought that it was more or less like writing any other React app.

To wrap my head around this I had to separate the build time from run time. At build time Gatsby.js pulls in data from different sources and generate pages from that data. Examples of sources are:

There are many more of these source plugins but I would advice someone who is just starting out to go with filesystem. This is because it makes it is easier create a mental image of how Gatsby.js works. It is easy to understand that these local files are managed at build time and not at run time. The thing that I didn't really understand at first was that even if the source was an API, the data was still fetched at build time.

Pages

Okay so lets talk basics. Pages are the most basic elements in Gatsby.js. When you create an app with the hello world starter pack you will only have one page, the index.js page. This page it the one that the user lands on. Another path will be added for each page that you add in the pages folder.

Let say that I add an about page. Gatsby.js will add a path for /about. You can now add a link from /index to /about.

// index.js
import { Link } from 'gatsby';

const Index = () => (
  <div>
    ...
    <Link to="/about">About</Link>
  </div>
);

export default Index;

GraphQL

So before making this blog I had never really worked with GraphQL on a "real" project. I had played around with GraphiQL but that was about all that I knew.

As I mentioned Gatsby pulls data from your sources at build time. Once the data is fetched it exposes this data though GraphQL. I found that the easiest one to wrap my head around was once again the filesystem. So I strongly recommend that you use that one and then play around with some queries in the GraphiQL. You can access GraphiQL at localhost:8000/___grapgql.

GraphQL queries can be used pretty much all over Gatsby and it is really really powerful.

Transformers

So gatsby has a multitude of transformers. What transformers do is to take the content that the source plugins load and transform them in some way.

I use remark. It is a transformer for markdown (my choice when writing stuff). It takes any markdown available from the sources and then transforms it in to HTML that can then be queried and displayed.

Generating Pages From the Sources

So it is quite easy to imagine how a page in the pages directory turns in to html but something that took a while for me to understand was how to create pages from the data that was fetched by the sources.

The answer was that at build time Gatsby tries to call a function, defined in gatsby-node.js, called createPages. In this method you can query for data with GraphQL and then call createPage to create the page.

I won't go in to much details about how to write this method. If you want to know more I would recommend reading the official documentation here.

What Finally Made It Click

Okay so the thing that finally made it click for me was to imagine that I was writing a express server with server side rendering. Gatsby will then pre-cache all the endpoints and stored them in the public directory.

So adding a file in the pages directory can be seen as writing:

app.get('/index');

And the gatsby-node.js file can be used to express endpoints that, in a express app, would be dynamic:

app.get('/posts/:postId');

Closing Thoughts

Gatsby is amazing! There are a lot of plugins and things that you can add. This can feel daunting at first but most of these plugins are nice to have but in no way required. So starting out with the basic hello world starter kit and then adding plugins as you need is probably the best way to get started.

Here is a list of plugins that I currently use, as of writing this post:

I found that, for me, thinking of it as an express server made it click. Hopefully someone else can benefit from this mental model too.