Skip to content

[feat]: warn when processing overly large images with gatsby-plugin-sharp #11798

DSchau asked this question in Ideas / Feature Requests
[feat]: warn when processing overly large images with gatsby-plugin-sharp #11798
Feb 15, 2019 · 1 answer

DSchau Feb 15, 2019


Images tend to be a key determinant in build-times growing exponentially large. In particular, overly large images processed in memory tend to put undue and unnecessary strain on the build process.

If these images are resized and optimized before processing, there are drastic improvements in build time and build performance (e.g. sometimes even resolving out of memory issues).

With this in mind--we should minimally do a few things:

  1. Document how to resize overly large images and why doing so is valuable (tracked in #24793)
  2. Augment gatsby-plugin-sharp to display a warning when overly large images are encountered

UPDATE: This issue now covers only item # 2, warning from the CLI. It has been filed internally as product feedback but we'll keep the issue open to also track it in the open.

Basic example

We should first create a docs page (that can be linked to from gatsby-plugin-sharp warning message) that conveys the why of optimizing images before processing.

Once created, we should then augment gatsby-plugin-sharp with the ability to warn on "overly large" images, where overly large images can be defined as: (note: this is fluid, needs some more research)

  • Image dimensions larger than a certain threshold, e.g. 2000 pixels wide
  • Image overall file size larger than a certain threshold, e.g. 2MB images
    • Note: this is probably even more important than the image width

When an image is processed that meets one or both of the above conditions, we should warn and link to the docs page that will be created as part of this issue. One note: if the requested image processing is itself large (e.g. requesting a 4000 pixel-wide hero image like below) we should short circuit and not warn in those cases.

  file(relativePath: { regex: "/i-am-overly-large-intentionally.jpg/" }) {
    childImageSharp {
      fluid(maxWidth: 4000) {


Consider an example from an awesome community member @oorestisime. He's working on a Gatsby blog, and has a large number of (large) images, some 3000 pixels wide and several megabytes large.

These images are resized using Gatsby's excellent image-processing capabilities with a max-width of 1000 pixels. As such, optimizing the images to be closer to the maximum size of images makes a ton of sense and the quality difference is negligible.

When building in CircleCI without optimization and the overly large images, the build actually times out.

Optimizing and resizing the images to 1000 pixels builds out the images in one minute 🏎️

Extra Detail


1 suggested answer


This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

Thanks for being a part of the Gatsby community! 💪💜

0 replies
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Ideas / Feature Requests
None yet
2 participants
Converted from issue