This site runs best with JavaScript enabled.

Illustrating Gatsby's Key Concepts

Last tended on August 20, 2020
🌱 Evergreen


The site you're currently on is built in a JavaScript framework called Gatsby.js. It's one of a host of new website builders based around static site-generation and the JAMStack JAM stands for JavaScript, APIs, and Markup. It's a relatively new approach to building websites that's been gaining popularity over the last half decade.

If you've heard of Gatsby before but haven't wrapped your head around it yet, this might be for you.

I already have some illustrated notes up on using the JAMStack with Gatsby & Contentful and Building Gatsby Themes, but they're a little more advanced.

Khaled Garbaya just put out an egghead course on Getting Started with Gatsby that's better suited to Gatsby beginners.

Course illustration of set of React-themed moving boxes and a road sign for Gatsby

Illustrating the Key Concepts

I've been working on a set of illustrations that capture the key concepts from Khaled's course. They don't summarise all the course content. They're just supporting material that help clarify the most important ideas.

First up is a big picture view showing all the essential parts of a Gatsby site.

Gatsby is a collection of tools for building static sites

Gatsby sites are able to pull in data from multiple sources all at once. This includes REST API endpoints, classic content management systems like Wordpress or Contentful, or just your local file system.

These are pulled in through GraphQL, which acts as a transportation layer.

Node.js is the main engine inside a Gatsby site which generates the pages, nodes, and metadata.

And finally React creates all the user interface elements.


Page Queries vs. Static Queries

Once people wrap their heads around the structure of a Gatsby project, GraphQL is usually one the first sticking points.

If you've never worked with it before, the syntax looks very odd and it's hard to tell what it's doing.

It gets more confusing to learn there are two types of queries - page queries and static queries

Diagram of a pageQuery request inside a page, and a static query request inside a component

It only seems complex on the surface, but it's easy to distinguish these two. Most of your queries will be page queries – these live inside your page files like blog.js or about.js

Static queries go inside individual component files like Navbar.js or Footer.js. There's also a handy React hook to handle these for us: useStaticQuery


Progressive Enhancement

One of the main benefits of a Gatsby site is it uses a technique called Progressive Enhancement to render pages.

Animation of a page rendering static HTML elements first, then being updates with React afterwards

This is what makes Gatsby page look like they load quickly. The lightweight static HTML version appears first, and then heavier files and interactive elements are layered on afterwards.

React handles any changes and user interactions. Once an element is clicked or changed, React "rehydrates" the page.


These illustrations are part of the egghead community notes on Khaled's Get Started with Gatsby course.

You can find more notes taken by people who have been through the course on there. If you take the course yourself, you can also add to them to the shared github repo.

Want to share?

Join the newsletter

For weekly notes on visual thinking, ethical technology, and cultural anthropology.

Maggie Appleton © 2020