Pitfalls to Avoid With Gatsby.js

A shortcut through the struggles I faced

If you don’t already know, Gatsby is a static site generator that has become the go-to for Node.js environment. This past spring I tried and failed to use it for a project. In this article I want to explain what confused me and what I have learned since.

These are some pitfalls to avoid, keep in mind they are connected so this might seem a bit scatterbrained, but I hope it helps

Approach Your project

Working in Gatsby has changed my mind set on how to approach websites.

Source before Content📄

With my first Gatsby website I wrote the whole thing using gatsby-source-filesystem and gatsby-transformer-remark. These packages allow you to create pages based on a template and markdown. This is a super great way of trying out Gatsby, and also a valid way of using it if you have just a small site with the markdown files included in the ./src directory. Buuut, if you plan on using Contentful or other CMS service, I would suggest starting with your content and then finishing with the code. Otherwise you will have to rewrite a lot of code, because data mapped from a CMS will be in a different format than from markdown.

Deciding on the Right Host 🔦

Gatsby is fast because it is full of optimization. Picking the right hosting can make or break this stream line experience.

When looking for static site benchmarks, I found Xavier Decuyper had a great article. Check it out here!

Since I am still a student, my criteria for a host were fast and free. So right out of the gate I knew my choices were Github Pages, Netlify, and Firebase.

Github Pages

Since I am connecting to Contentful I need a place for environment variables, which knocks out Github Pages right away.

Netlify Hosting Network Console


I chose Netlify originally because they are free, and recommended by Gatsby docs. But upon further review they have a higher latency than many other providers.

Firebase Hosting Network Console


Since Firebase is able to leverage much of Google Cloud’s infrastructure, it comes out much faster than Netlify.

I chose to host on Firabse, but the other platforms have their merits as well so don’t blindly make your decision. Github pages is a great option if you don’t need to store environment variables, because it is integrated right into your source control, and Netlify is a great if you want lots of build and webhook options.

Explore for yourself!


Gatsby Image provides a lot of the overhead needed to lazy load images. Three things to keep in mind when using Gatsby Image are sizing, fragments, and positioning.


Responsive images can be lazy loaded in two ways

  • Resolutions — For fixed width and height
  • Sizes — For stretching images accross variable dimension

This was confusing to me at first and it took some work to figure out when to use both. TLDR: Use Resolutions for icons and logos, and use Sizes for real pictures and backgrounds.


Step 0: Verify that you have correct query
Step 1: Insert fragment and specs

Fragments allow us to cut the repetition between image querying, and are each named according to their function. Unfortunately, they are not currently supported by the GraphiQL IDE.


Positioning Gatsby Images can also be difficult, especially if you treat them like regular images tags. Gatsby-Images have two wrapping divs, which can result in some unexpected behavior.

Img tag upon inspection

There are three ways of styling Gatsbys Images.

  1. Inline style tag
  2. ClassName tag
  3. Global altering of gatsby-image-outer-wrapper and gatsby-image-wrapper in css
Inline styles example
ClassName example

Whatever you choose just be consistent, and don’t use inline styles 😋


If you haven’t used a static site generator before, the Layout, Template, Pages, and Components folders can be daunting. I will probably cover their purposes in another article, but for now here are some things that I found super annoying when I was first learning.

Graphql and where to use it!

Graphql is a great tool especially when paired with the GraphiQl IDE found at http://localhost:8000/___graphql. That said it was very confusing at first because the docs say that querying data is only allowed from layouts and pages. This is especially confusing, because if you are generating pages from markdown, you can only use queries in the layout, when you need to query from templates. For the record, querying from templates is fine. I have done it in multiple projects.

Templating Everything

At some point in my projects I started templating everything. That is tempting. Especially, in the above case, because the only other place to query Graphql, if you are generating pages from markdown, is from the base layout.

In general you should use pages for single pages, templates multiple similar pages, and layouts for static site wide data only


That wraps up the list of stumbling blocks I found on my journey to learning Gatsby. Now that I am 4 sites deep, however it’s proved to be well worth the struggle.

Check out my portfolio. I finished it yesterday with the help of Gatsby.js!






Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

OFTW : Chapter 8, Project Quality Management

Elgato Stream Deck Review

Elgato Stream Deck Review

Having fun with iOS and connectivity

An Ode to Email

5 Different Git Workflows

Octoparse 8 vs Octoparse 7 Comparison: What’s New in 8.1?

Flutter CI/CD, Which One and Why

Node.js vs PHP. Choosing Between Modernity and Tradition

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Joshua Wootonn

Joshua Wootonn


More from Medium

Build React components with Fluent UI

Flatfile | Made with Gatsby JS

Advanced features on Gouache

How to create React components library using Stencil.js