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
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
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!
Images
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.
Sizing
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.
Fragments
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
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.
There are three ways of styling Gatsbys Images.
- Inline style tag
- ClassName tag
- Global altering of gatsby-image-outer-wrapper and gatsby-image-wrapper in css
Whatever you choose just be consistent, and don’t use inline styles 😋
Structure
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
Conculsion
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!
