Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

DSchau opened this Issue Feb 15, 2019 · 1 comment


None yet
2 participants
Copy link

DSchau commented 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
  2. Augment gatsby-plugin-sharp to display a warning when overly large images are encountered

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

@oorestisime oorestisime self-assigned this Feb 15, 2019

oorestisime added a commit to oorestisime/gatsby that referenced this issue Feb 15, 2019

DSchau added a commit that referenced this issue Feb 22, 2019

docs: add preoptimizing your images documentation (#11809)
Contributes: #11798

I am not sure this was the best place possible to add this part of documentation. 
Let me know if you think it is more appropriate to move this elsewhere (in plugin-sharp ?)

oorestisime added a commit to oorestisime/gatsby that referenced this issue Feb 27, 2019


This comment has been minimized.

Copy link

gatsbot bot commented Mar 8, 2019


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! 💪💜

@gatsbot gatsbot bot added the stale? label Mar 8, 2019

@DSchau DSchau added not stale and removed stale? labels Mar 8, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.