Gatsby Headaches: Dealing with Media (Part 1)

Juan Diego Rodríguez, also known by his alias Monknow, is a Venezuelan front-end developer with a passion for creating visually appealing websites using the latest technologies. You can learn more about Juan Diego here.

Receive weekly advice on front-end and UX, trusted by over 200,000 individuals.

Working with media files in Gatsby can be more complex than initially anticipated. I recall embarking on my first Gatsby project and realizing, after perusing Gatsby's documentation, that I needed to utilize the gatsby-source-filesystem plugin to query local files. Simple enough, right?

However, the process quickly became more intricate. Need to incorporate images? Consult the documentation and install one or several of the numerous plugins designed for image handling. What about SVG files? There's a plugin for that. Video files? You see where this is going.

Everything is fine until any of these plugins or packages become obsolete and are no longer maintained. That's when the real challenges begin.

If you're not familiar with Gatsby, it's a static site generator based on React that uses GraphQL to extract structured data from various sources. It employs webpack to bundle a project for deployment and serving as static files. Essentially, it's a static site generator with reactivity that can draw data from a wide range of sources.

Like many static site frameworks in the Jamstack, Gatsby has traditionally been praised for its performance. However, its reputation has suffered in recent years. From my observations, the issue isn't so much about the speed of the framework, but rather how it's configured to manage factors that affect performance, including media files.

So, let's address the potential issues you may face when dealing with media files in a Gatsby project. This article is the first in a short two-part series where we will focus on the most commonly used media: images, video, and audio. The second part of this series will delve into different file types, including Markdown, PDFs, and even 3D models.

I believe that image optimization can be categorized into four distinct areas:

These principles are applicable to any website, not just those built with Gatsby. However, integrating them into a Gatsby-powered site can be perplexing, which is why I'm writing this article and possibly why you're reading it.

Here's how to apply an image to a React component in a Gatsby site:

It's crucial to import the image as a JavaScript module. This informs webpack to bundle the image and generate a path to its location in the public folder.

This method works well, but what if we're dealing with more than one image? What if we want to create an image gallery with 100 images? Loading that many tags simultaneously could slow things down and potentially impact the FCP. This is where the third principle, which utilizes the loading="lazy" attribute, becomes useful.

We can do the reverse with loading="eager". This tells the browser to load the image immediately, regardless of whether it's onscreen or not.

Here's a basic example of the HTML for responsive images:

In Gatsby, we need to import the images first and pass them to the srcset attribute as template literals so webpack can bundle them:

This should alleviate any future issues with responsive images.

What if we need to pull in the URL for an image file to use on the CSS background-url property? It would look something like this:

This is straightforward, but there's still room for improvement! For instance, we can implement the CSS version of responsive images, which loads the desired version at specific breakpoints.

Before we proceed, I recommend installing the gatsby-source-filesystem plugin. It's an essential...