[docs] Document how to resize overly large images and why doing so is valuable

[marcysutton]

Summary

The Gatsby docs would benefit from some instructions on how to resize overly large images before processing them with gatsby-plugin-sharp. By sizing images down before running a CLI process, machines have a heck of a lot easier time processing them (think giant images from SLRs or modern phones, etc.).

This issue was spun off from #11798, so that it could be handled independently. Rather than creating a new doc, these changes could be added to the existing doc, Using Gatsby Image to Prevent Bloat. Applications/tips it could include:

• Sizing for Web / Screens with Photoshop, Illustrator, etc.
• Compressing with ImageOptim, ImageAlpha
• Using ImageMagick on the command-line or the ImageMagick Studio
• File size recommendations: dimensions (3000 pixels on the longest side?), weight (<5MB?), format (JPG/PNG/GIF, not RAW), etc.
• Other recommendations welcome

Motivation

All Gatsby developers who want to include high-resolution imagery would benefit from documentation of how to speed up build processes.

Steps to resolve this issue

Add content to the Gatsby Image doc on preventing image bloat that instructs users how to resize images so a machine doesn't have to work so hard to process them

Draft the doc

• Write the new content, following the format listed in these resources:
  • Overview on contributing to documentation

Open a pull request

• Open a pull request with your work including the words "closes #[this issue's number]" in the pull request description

[polarathene]

Image format only matters for disk I/O, it'll decompress to full size in memory afaik(for majority of formats anyhow), so the only benefit there is optimizing for slow storage media by choosing a format that uses less on-disk file size/weight.

The user should probably try to avoid reducing weight by format due to lossy compression as that'd result in lossy data being sent to sharp to process re-compress the image again, reducing image quality further.

Prioritizing dimensions/pixels via resize would be the smarter route, reducing the weight accordingly. If bringing image format into it, using lossless compression or light lossy compression would be fine, just don't optimize too heavily for size through image codecs when these images are being pre-processed for as intermediary data for presenting less load on sharp(or any other image processor at this stage) during builds.

---

Using a CLI tool for automating the processing is good. For some developers it might be better if the process was more streamlined, most already have plenty to deal with. A docker image may be a reliable and consistent way to ensure everyone uses the same dependencies and can more reliable reproduce issues users experience.

The docker image can still work as a CLI tool, be it just wrapping something like ImageMagick and forwarding the commands, or providing a few simple commands from the user like the entrypoint script shown for this gatsby dev image.

Another option would be to utilize sharp via node and add a gatsby-cli command like gatsby preprocess/gatsby prepare, which could support/read options from a config with general best practice defaults, users wouldn't need to know much more than running that once, and then looking up config to change if any defaults aren't suitable for them.

---

For image formats, WebP might be a good one, it covers most needs afaik(at least regarding image content for web), lossless or lossy compression options. Also has better support for animated graphics than GIF, though I'm not sure how well that converts to GIF, generally GIF isn't desirable and you'll find certain services use GIFV instead which is a GIF converted to an MP4 clip.

[tiafreeman]

Hi, I would love to help out with this (this will be my first contribution to this project if that matters but it seems like a good place to start!)

[marcysutton]

Hey there, since opening this issue I realized there is a doc on Preoptimizing Images with a Sharp script: https://www.gatsbyjs.org/docs/preoptimizing-images/

It's a bit short, and doesn't mention any alternative approaches. Perhaps that doc could be updated a bit to mention things like Photoshop and other pixel-level editors, ImageMagick, etc.?

We would welcome your contribution, @tiafreeman! Let us know if you have any questions.

[polarathene]

If it would be helpful at all, I've made a small sharp script for one of my projects to pre-process ~150MB of JPG images down to ~10MB from scaling images down to the max breakpoint dimensions gatsby will process from, along with some cropping and a little compression.

It's a little specific to my project, so I'm not sure if it's useful in a guide, but might be a good reference/snippet/example for it? I process a JSON file with the image file paths and some metadata for transforms to perform on the images, but for docs, it could be altered to just process a folder of images to a max width/height and quality output folder?