Set up automatic image optimization pipeline (#5779)

Use 11ty's first-party [image transformation
plugin](https://www.11ty.dev/docs/plugins/image/) to automatically
optimize images, convert them to `png`, `webp`, and `avif`, and then
transform the site HTML to use the [`<picture>`
element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture)
to select the best one for the user. This only runs in production deploy
builds to reduce serving time. Also applies lazy loading and async
decoding to all images, even when serving without optimizations. The
transform also adds a hash of the image, allowing us to expand caching
for images in Firebase hosting.

To account for the transformed HTML structure, some minor HTML and CSS
changes were needed as well.

Overall, this reduces page load time on pages that use images, and
reduces unnecessary downloads that were due to a relatively short cache
time for images. On a page with just a few images, such as
https://dart.dev/tools/pub/automated-publishing, the lighthouse perf
score increases around 10-15 points.

Fixes #4473
Fixes #3124

Author: parlough

.gitignore

@@ -1,5 +1,6 @@
 _cache/
 _site/
+.cache
 .*-cache
 .*-metadata
 .buildlog

eleventy.config.js

@@ -19,6 +19,7 @@ import yaml from 'js-yaml';
 
 import * as path from 'node:path';
 import * as sass from 'sass';
+import {eleventyImageTransformPlugin} from '@11ty/eleventy-img';
 
 // noinspection JSUnusedGlobalSymbols
 /**
@@ -27,6 +28,7 @@ import * as sass from 'sass';
  */
 export default function (eleventyConfig) {
   const isProduction = process.env.PRODUCTION === 'true';
+  const shouldOptimize = process.env.OPTIMIZE === 'true';
 
   eleventyConfig.on('eleventy.before', async () => {
     await configureHighlighting(markdown);
@@ -71,7 +73,7 @@ export default function (eleventyConfig) {
       }
 
       const result = sass.compileString(inputContent, {
-        style: isProduction ? 'compressed' : 'expanded',
+        style: shouldOptimize ? 'compressed' : 'expanded',
         quietDeps: true,
         loadPaths: [parsedPath.dir, 'src/_sass'],
       });
@@ -101,7 +103,7 @@ export default function (eleventyConfig) {
     'src/content/guides/language/specifications',
   );
 
-  if (isProduction) {
+  if (shouldOptimize) {
     // If building for production, minify/optimize the HTML output.
     // Doing so during serving isn't worth the extra build time.
     eleventyConfig.addTransform('minify-html', async function (content) {
@@ -118,6 +120,37 @@ export default function (eleventyConfig) {
 
       return content;
     });
+
+    // Optimize all images, generate an avif, webp, and png version,
+    // and indicate they should be lazily loaded.
+    // Save in `_site/assets/img` and update links to there.
+    eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
+      extensions: 'html',
+      formats: ['avif', 'webp', 'png', 'svg'],
+      svgShortCircuit: true,
+      widths: ['auto'],
+      defaultAttributes: {
+        loading: 'lazy',
+        decoding: 'async',
+      },
+      urlPath: '/assets/img/',
+      outputDir: '_site/assets/img/',
+    });
+  } else {
+    // To be more consistent with the production build,
+    // don't optimize images but still indicate they should be lazily loaded.
+    // Then save in `_site/assets/img` and update links to there.
+    eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
+      extensions: 'html',
+      formats: ['auto'],
+      widths: ['auto'],
+      defaultAttributes: {
+        loading: 'lazy',
+        decoding: 'async',
+      },
+      urlPath: '/assets/img/',
+      outputDir: '_site/assets/img/',
+    });
   }
 
   eleventyConfig.setQuietMode(true);

firebase.json

@@ -5,12 +5,19 @@
     "trailingSlash": false,
     "headers": [
       {
-        "source": "**/*.@(jpg|jpeg|gif|png|md|txt|json|webp|webm|svg|css|js)",
+        "source": "**/*.@(avif|jpg|jpeg|gif|png|md|txt|json|webp|webm|svg|css|js)",
         "headers": [
           { "key": "Cache-Control", "value": "max-age=28800" },
           { "key": "Access-Control-Allow-Origin", "value": "*" }
         ]
       },
+      {
+        "source": "/assets/img/*.@(jpg|jpeg|png|webp|avif)",
+        "headers": [
+          { "key": "Cache-Control", "value": "max-age=604800" },
+          { "key": "Access-Control-Allow-Origin", "value": "*" }
+        ]
+      },
       {
         "source": "**",
         "headers": [

package.json

@@ -10,8 +10,8 @@
   },
   "scripts": {
     "serve": "PRODUCTION=false eleventy --serve",
-    "build-site-for-staging": "PRODUCTION=false eleventy",
-    "build-site-for-production": "PRODUCTION=true eleventy"
+    "build-site-for-staging": "PRODUCTION=false OPTIMIZE=true eleventy",
+    "build-site-for-production": "PRODUCTION=true OPTIMIZE=true eleventy"
   },
   "engines": {
     "node": ">=20.10.0",
@@ -23,6 +23,7 @@
   },
   "devDependencies": {
     "@11ty/eleventy": "3.0.0-alpha.10",
+    "@11ty/eleventy-img": "^4.0.2",
     "firebase-tools": "^13.10.2",
     "hast-util-from-html": "^2.0.1",
     "hast-util-select": "^6.0.2",