Unwanted cache key mutation causes poor build performance

[sentience]

TL;DR: I'm seeing in-memory cache misses for identical <img> tags in my site that should be hitting.

I have traced the issue to the re-use of the GLOBAL_OPTIONS object:

eleventy-img/src/image.js

Line 74 in fbca166

this.options = Object.assign({}, GLOBAL_OPTIONS, options);

Some fields of GLOBAL_OPTIONS contain objects (e.g. htmlOptions):

eleventy-img/src/global-options.js

Lines 84 to 94 in fbca166

	// Defaults used when generateHTML is called from a result set
	htmlOptions: {
	imgAttributes: {},
	pictureAttributes: {},
	whitespaceMode: "inline", // "block"
	// the <img> will use the largest dimensions for width/height (when multiple output widths are specified)
	// see https://github.com/11ty/eleventy-img/issues/63
	fallback: "largest", // or "smallest"
	},

The htmlOptions.imgAttributes object (among others, possibly) gets mutated when processing an image:

eleventy-img/src/image.js

Lines 324 to 326 in fbca166

	// used when results are passed to generate HTML, we maintain some internal metadata about the options used.
	let imgAttributes = this.options.htmlOptions?.imgAttributes || {};
	imgAttributes.src = this.src;

This mutation is then present in the GLOBAL_OPTIONS object used by subsequent images in the build, causing cache misses for the same image since the options object used in the calculation of the cache key does not match.

Fixing this issue takes my site build from ~30 minutes to ~5 minutes! 🎉

---

Original issue:

I've just added an image gallery to my site, where each page that displays a full-size image also has all the other images' thumbnails on it (to provide "filmstrip"-style navigation between images). As a result, my site has many identical references to the same source image, which all look like this:

<img
  src="{{ image.src }}"
  alt="{{ image.alt }}"
  class="h-full w-full object-cover transition-transform hover:scale-105"
  eleventy:widths="428,856,268,536,204,408,160,320,288,576"
  sizes="(min-width: 1920px) 428vw, (min-width: 1280px) 268px, (min-width: 1024px) 204px, (min-width: 768px) 160px, (min-width: 640px) 288px, 591px"
  {% unless galleryImage %}
    style="view-transition-name: {{ image.src | slugifyImageSrc }};"
  {% endunless %}
>

While the Image plug-in's build caching works great to accelerate subsequent builds, the initial build takes an extremely long time. Looking at the build output as it runs, it looks to me like these gallery thumbnail images are being processed over and over again (once for each page on which they appear), even though they should have identical input and output, which would make me expect the build output to be reused by these multiple img tags:

CleanShot.2025-12-01.at.12.14.34.mp4

Any chance I'm doing something wrong here? At this point my initial build takes over 30 minutes on my host (CloudCannon), which causes it to time out and fail. I can then trigger another build that runs in under 2 minutes thanks to the cached output of the failed build, but this is not a workable workflow for the non-technical contributors to my site.

This is with @11ty/eleventy-img@6.0.1, and this is my plugin configuration:

  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    urlPath: "/img/",
    outputDir: "node_modules/.cache/@11ty/img/",
    svgShortCircuit: "size",
  });
  eleventyConfig.on("eleventy.after", () => {
    fs.cpSync(
      "node_modules/.cache/@11ty/img/",
      path.join(eleventyConfig.directories.output, "/img/"),
      { recursive: true },
    );
  });

[sentience]

This issue seems like it may be caused by “pollution” of the DEFAULTS object defined in global-options.js:

eleventy-img/src/global-options.js

Lines 7 to 11 in fbca166

	const DEFAULTS = {
	widths: ["auto"],
	formats: ["webp", "jpeg"], // "png", "svg", "avif"
	formatFiltering: ["transparent", "animated"],

image.js uses Object.assign to splat these defaults into the options field of each new Image object:

eleventy-img/src/image.js

Line 74 in fbca166

this.options = Object.assign({}, GLOBAL_OPTIONS, options);

…however, fields like htmlOptions contain mutable objects that are shared with DEFAULTS. When these are assigned values for the current image, they also get stored in DEFAULTS, and reused for subsequent images in the build!

Some pretty-printed debug output showing this in my site's build:

  Eleventy:Image Unique images processed: 1 +0ms
  Eleventy:Image Processing './images/logo/open-graph.jpg' (in-memory cache miss), options:
  {
    widths: [ 1200 ],
    formats: [ 'jpeg', 'png' ],
    formatFiltering: [ 'transparent', 'animated' ],
    concurrency: 12,
    urlPath: '/img/',
    outputDir: 'node_modules/.cache/@11ty/img/',
    svgShortCircuit: false,
    svgAllowUpscale: true,
    svgCompressionSize: '',
    sharpOptions: {},
    sharpWebpOptions: {},
    sharpPngOptions: {},
    sharpJpegOptions: {},
    sharpAvifOptions: {},
    formatHooks: {
      svg: [AsyncFunction: createSvg]
    },
    cacheDuration: '1d',
    cacheOptions: {},
    filenameFormat: [Function: filenameFormat],
    urlFormat: null,
    statsOnly: false,
    remoteImageMetadata: {},
    useCache: true,
    dryRun: false,
    hashLength: 10,
    fixOrientation: false,
    minimumThreshold: 1.25,
    transformOnRequest: false,
    transform: undefined,
    returnType: 'object',
    htmlOptions: {
      imgAttributes: {},
      pictureAttributes: {},
      whitespaceMode: 'inline',
      fallback: 'largest'
    }
  } +0ms
  Eleventy:Image Concurrency: 12, Size: 0, Pending: 0 +0ms
  Eleventy:Image Wrote 'node_modules/.cache/@11ty/img/dGRKfFxfJ5-1200.jpeg' +3ms
  Eleventy:Image Wrote 'node_modules/.cache/@11ty/img/dGRKfFxfJ5-1200.png' +1ms
  Eleventy:Image Unique images processed: 2 +24ms
  Eleventy:Image Processing './images/logo/open-graph.jpg' (in-memory cache miss), options:
  {
    widths: [ 1200 ],
    formats: [ 'jpeg', 'png' ],
    formatFiltering: [ 'transparent', 'animated' ],
    concurrency: 12,
    urlPath: '/img/',
    outputDir: 'node_modules/.cache/@11ty/img/',
    svgShortCircuit: false,
    svgAllowUpscale: true,
    svgCompressionSize: '',
    sharpOptions: {},
    sharpWebpOptions: {},
    sharpPngOptions: {},
    sharpJpegOptions: {},
    sharpAvifOptions: {},
    formatHooks: {
      svg: [AsyncFunction: createSvg]
    },
    cacheDuration: '1d',
    cacheOptions: {},
    filenameFormat: [Function: filenameFormat],
    urlFormat: null,
    statsOnly: false,
    remoteImageMetadata: {},
    useCache: true,
    dryRun: false,
    hashLength: 10,
    fixOrientation: false,
    minimumThreshold: 1.25,
    transformOnRequest: false,
    transform: undefined,
    returnType: 'object',
    htmlOptions: {
      imgAttributes: { src: './images/logo/open-graph.jpg' },
      pictureAttributes: {},
      whitespaceMode: 'inline',
      fallback: 'largest'
    }
  } +19ms
  Eleventy:Image Concurrency: 12, Size: 0, Pending: 0 +23ms
  Eleventy:Image Wrote 'node_modules/.cache/@11ty/img/dGRKfFxfJ5-1200.jpeg' +8ms
  Eleventy:Image Wrote 'node_modules/.cache/@11ty/img/dGRKfFxfJ5-1200.png' +1ms

Notice that the first instance of ./images/logo-open-graph.jpg is processed with an options object containing the default, mostly-empty htmlOptions, but the second instance of the same image is processed with an options object containing an htmlOptions.imgAttributes.src value. Even though the markup for these two images is identical, the second counts as a cache miss because the options object is different.

After that, the build correctly cache-hits several more instances of the same image (since the "polluted" options object matches in each case), but then the next image shows that the polluted options object is still being used:

  Eleventy:Image Processing 'images/logo/mpss-logo-horizontal-full.svg' (in-memory cache miss), options:
  {
    widths: [ 490 ],
    formats: [ 'png', 'svg' ],
    formatFiltering: [ 'transparent', 'animated' ],
    concurrency: 12,
    urlPath: '/img/',
    outputDir: 'node_modules/.cache/@11ty/img/',
    svgShortCircuit: 'size',
    svgAllowUpscale: true,
    svgCompressionSize: '',
    sharpOptions: {},
    sharpWebpOptions: {},
    sharpPngOptions: {},
    sharpJpegOptions: {},
    sharpAvifOptions: {},
    formatHooks: {
      svg: [AsyncFunction: createSvg]
    },
    cacheDuration: '1d',
    cacheOptions: {},
    filenameFormat: null,
    urlFormat: null,
    statsOnly: false,
    remoteImageMetadata: {},
    useCache: true,
    dryRun: false,
    hashLength: 10,
    fixOrientation: false,
    minimumThreshold: 1.25,
    transformOnRequest: false,
    transform: undefined,
    returnType: 'object',
    htmlOptions: {
      imgAttributes: { src: './images/logo/open-graph.jpg' },
      pictureAttributes: {},
      whitespaceMode: 'inline',
      fallback: 'largest'
    },
    packages: {
      image: [Function: queueImage] {
        Util: [Function],
        Image: [class Image],
        ImagePath: [class ImagePath],
        ImageSize: [Function],
        statsSync: [Function: statsSync],
        statsByDimensionsSync: [Function: statsByDimensionsSync],
        getFormats: [Function: getFormatsArray],
        getWidths: [Function: getValidWidths],
        getHash: [Function: getHash],
        setupLogger: [Function: setupLogger],
        generateHTML: [Function],
        generateObject: [Function: generateObject],
        eleventyImagePlugin: [Function: eleventyWebcOptionsPlugin],
        eleventyImageWebcOptionsPlugin: [Function: eleventyWebcOptionsPlugin],
        eleventyImageTransformPlugin: [Function: eleventyImageTransformPlugin],
        eleventyImageOnRequestDuringServePlugin: [Function: eleventyImageOnRequestDuringServePlugin]
      }
    },
    failOnError: true,
    extensions: 'html',
    directories: ProjectDirectories {
      inputFile: undefined,
      inputGlob: undefined
    },
    generatedVia: 'transform'
} +248ms

The image being processed is 'images/logo/mpss-logo-horizontal-full.svg', but you can see the htmlOptions object still contains the imgAttributes: { src: './images/logo/open-graph.jpg' }!

I am going to attempt a fix for this by creating a fresh DEFAULTS object for each image, rather than reusing the one that may have been mutated by previous images in the build.

[sentience]

Fix is here for v7 alpha: #313

Fix for @11ty/eleventy-img v6.0.4 (current release) is here: https://github.com/sentience/eleventy-img/tree/fix-global-options-pollution

If someone is able to stand up a v6 maintenance branch, I will happily open a PR to contribute this fix.