Image v7.0.0: The Memory Efficiency Release

TL;DR: ESM-only, Node 22+ minimum, and huge memory and performance wins over v6.

Thank you to @sentience, @valadaptive, @kirthi-b, @jens-struct, and @jornmineur for their contributions to this release!

Issue Milestone: https://github.com/11ty/eleventy-img/milestone/25?closed=1
Full Changelog: v6.0.4...v7.0.0

Breaking changes

• Node 22 or newer is required. This matches Core v4. #351
• The package is now ESM. This is unlikely to require any changes as the Node minimum now supports require(esm). #300
  • ESM: import Image from "@11ty/eleventy-img"
  • CommonJS friendly: const Image = await import("@11ty/eleventy-img")
• Upgrades sharp from v0.33 to v0.35 #352, #289
  • You can review the upstream v0.34 and v0.35 changelogs.

And a few breaking changes that are unlikely to affect most projects:

• If you use the Transform method and set both width and eleventy:widths on the same element, note that eleventy:widths now takes priority. #314
• Image.statsSync and Image.statsByDimensionsSync have been removed after being deprecated in 2024. Use the statsOnly feature instead, like so: await Image(src, { statsOnly: true, /* …options */ }). Helpful error messaging is provided if your project uses these (so don’t worry about it until you run into it, they weren’t commonly used). #211 #295
• Removes the <eleventy-image> WebC component (use the transform method instead) #305

New Features

• New passthrough format (usage: formats: ["passthrough"]) copies and uses the source file directly, while still adding width and height attributes to the generated output. Useful when you've already optimized your source images and want to skip the optimization pipeline — about 20× faster in local benchmarks. Example on #212. Also #133, #183, #309
• New eleventy:sizes attribute allows overriding any sizes attribute in markup #306
• New manualCacheKey option to improve the cropping API #271 #274 by @jens-struct

Bug Fixes

• Huge memory usage improvements from @sentience in #313 and @jornmineur in #302 #319 (v6 had issues, but we’ve eclipsed v5 performance with this release 🏆)
• Removes the w descriptor when only one size is used in srcset, fixing valid HTML output when only one width is used and no sizes is present (#298).
• Fixes eleventy:ignore appearing in output on <img> tags inside <picture> elements — by @valadaptive in #303.
• Decodes HTML entities on <img src> when read back from HTML, by @kirthi-b #349 #307

Internals

• Swaps the debug dependency for obug (#356).
• Major version dependency upgrade: upgrades p-queue from v6.6 to v8.1. #120 This dependency became ESM-only in v7 and Node 18+ in v8.

Image v7.0.0-alpha.5

This is likely the last pre-release before v7 stable.

• Breaking change: Node minimum is now 22+ (matching core v4) #351
• Breaking change: removes deprecated (since 2024) synchronous functions Image.statsSync and Image.statsByDimensionsSync #211 #295
• Breaking change: ugprades to sharp v0.35 #352 see upstream sharp changes
• Fix: removes w descriptor when only one size is used in srcset, fixes valid HTML output when only one width is used and no sizes present #298
• Feature: Adds new special passthrough format (usage: formats: ["passthrough"]) to copy and use the source file directly (still adds width and height attributes in generated output). Useful when you don’t want the optimization pipeline (and have already optimized your source images). About 20× faster in local benchmarks. Example on issue #212 Also #133 #183 #309
• Fix: Decode HTML entities in image src when read back from HTML by @kirthi-b #349 #307
• Feature: Adds manualCacheKey option to improve cropping API #271 #274 by @jens-struct
• Fix: bug with bounded memory usage on large builds by @jornmineur #302 #319
• Internals: swap from debug to obug dependency #356
• Feature: Adds eleventy:sizes attribute which allows overriding any sizes attribute in markup #306

Thank you to @kirthi-b, @jens-struct, and @jornmineur

Full Changelog: v7.0.0-alpha.4...v7.0.0-alpha.5

Image v7.0.0-alpha.4

• Breaking change: eleventy:widths will supersede width on Transform method #314
• Fix poor in-memory cache performance due to accidental mutation of global object used in cache keys by @sentience in #313
• Fix eleventy:ignore was appearing in output (Call cleanTag on <img> tags inside <picture>s too) by @valadaptive in #303

New Contributors

• @sentience made their first contribution in #313
• @valadaptive made their first contribution in #303

Milestone: https://github.com/11ty/eleventy-img/milestone/25?closed=1
Full Changelog: v7.0.0-alpha.2...v7.0.0-alpha.4

Image v7.0.0-alpha.3

Regression in npm prevented publish on this one. Use v7.0.0-alpha.4 instead.

Eleventy Image v7.0.0-alpha.2

• Removes eleventy-image.webc component #305
• Upgrades dev dep pixelmatch from v5 to v7

Full Changelog: v.7.0.0-alpha.1...v7.0.0-alpha.2

Eleventy Image v7.0.0-alpha.1

• Package is now using ESM #300. Now requires import, import(), or require(esm) in Node (v22.12.0, v20.19.0, or newer) to use.
  • Example (ESM only): import Image from "@11ty/eleventy-img"
  • Example (CommonJS friendly): const Image = await import("@11ty/eleventy-img")
• Breaking changes in sharp@0.33 upgrade to 0.34: https://sharp.pixelplumbing.com/changelog/#v0340---4th-april-2025
• Major dependency upgrade: p-queue@6.6 to 8.1 #120
  • ESM-only as of v7 https://github.com/sindresorhus/p-queue/releases/tag/v7.0.0
  • Node 18+ as of v8 https://github.com/sindresorhus/p-queue/releases/tag/v8.0.0

Issue Milestone: https://github.com/11ty/eleventy-img/milestone/25?closed=1
Full Changelog: v6.0.4...v.7.0.0-alpha.1

Eleventy Image v6.0.4

• Internals revert of #294, which caused #296 (hangs when using Eleventy serve in transform method)

Milestone: https://github.com/11ty/eleventy-img/milestone/27?closed=1
Full Changelog: v6.0.3...v6.0.4

Eleventy Image v6.0.3

• Adds Node v24 to CI test suite
• Swap to use the image-size asynchronous API internally (when using statsOnly option) #294
• Adds ImageSize export to reuse internal image-size package
• Reuses multi-runtime hashing utility from @11ty/eleventy-utils@2.0.6
• Upgrade devDependencies
• Migrate to flat config with @stylistic/eslint-plugin-js by @outslept in #292

Milestone: https://github.com/11ty/eleventy-img/milestone/26?closed=1
Full Changelog: v6.0.2...v6.0.3

Eleventy Image v6.0.2 (dependency bump for security audit)

• bump image-size minimum version for security by @joshvickerson in #290

Milestone: https://github.com/11ty/eleventy-img/milestone/24?closed=1
Full Changelog: v6.0.1...v6.0.2

Eleventy Image v6.0.1 (Tiny Bugfix Release)

• Bug fix when using animated images with transformOnRequest #273

Milestone: https://github.com/11ty/eleventy-img/milestone/23?closed=1
Full Changelog: v6.0.0...v6.0.1