From 20edbc550ea93045541dc0583b095ff2609fd86e Mon Sep 17 00:00:00 2001 From: Orestis Ioannou Date: Sat, 23 Feb 2019 00:18:18 +0100 Subject: [PATCH] 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 ?) --- docs/docs/preoptimizing-images.md | 48 ++++++++++++++++++++++++++++ www/src/data/sidebars/doc-links.yaml | 2 ++ 2 files changed, 50 insertions(+) create mode 100644 docs/docs/preoptimizing-images.md diff --git a/docs/docs/preoptimizing-images.md b/docs/docs/preoptimizing-images.md new file mode 100644 index 0000000000000..e0af4bbbda223 --- /dev/null +++ b/docs/docs/preoptimizing-images.md @@ -0,0 +1,48 @@ +--- +title: Preoptimizing your Images +--- + +Gatsby ships with excellent image optimization capabilities (see the [Image Tutorial](/docs/image-tutorial/) for more info). However, this image optimization can come with a cost. It can be fairly CPU intensive, and in some cases may lead to long build times. As a means of debugging and perhaps improving your overall build performance, it _may_ be helpful to pre-optimize your (extremely large) images. + +First, some context. `gatsby-plugin-sharp` ships with a `fluid` option which will attempt to create five images intended to map to various screen resolutions. Producing multiple images ensures that your images are ready and optimized for phone displays, desktop displays, and everything in between. This plugin receives a non-optimized image and produces optimized images for _all_ of your users and devices. Magic! + +If you find yourself running into build performance issues, it could be helpful to consider applying some image optimizations. Images in your setup _could_ be overly large, especially compared to the requested image sizes in your layout (e.g. if your layout has a max width of 600 pixels). + +For instance, if your layout is 600 pixels wide, then the highest resolution image you will need is 1800 pixels to account for 3x pixel density. If you have images that are 3000 or 4000 pixels wide then you could resize your image to 1800 pixels, which may improve overall build performance. + +Here's an example script to pre-optimize your image dimensions and slightly compress. This optimization may serve as a helpful technique to possibly improve build time if your local repository has many, very large images. + +```js:title=scripts/optimize.js +const sharp = require(`sharp`) +const glob = require(`glob`) +const fs = require(`fs-extra`) + +const matches = glob.sync(`src/images/**/*.{png,jpg,jpeg}`) +const MAX_WIDTH = 1800 +const QUALITY = 70 + +Promise.all( + matches.map(async match => { + const stream = sharp(match) + const info = await stream.metadata() + + if (info.width < MAX_WIDTH) { + return + } + + const optimizedName = match.replace( + /(\..+)$/, + (match, ext) => `-optimized${ext}` + ) + + await stream + .resize(MAX_WIDTH) + .jpeg({ quality: QUALITY }) + .toFile(optimizedName) + + return fs.rename(optimizedName, match) + }) +) +``` + +The variables `MAX_WIDTH` and `QUALITY` should be configured in regards to your particular website's layout. Quality can be lowered further for perhaps more gains in performance, but be aware that it can introduce visual differences between the original and optimized images, so be sure to compare before over optimizing. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index f0e1a883944ea..fec04b5b460e1 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -76,6 +76,8 @@ link: /docs/working-with-images/ - title: Using gatsby-image link: /docs/using-gatsby-image/ + - title: Preoptimizing your Images + link: /docs/preoptimizing-images/ - title: Sourcing content and data link: /docs/content-and-data/ items: