image/4/io
Framework Guides· Framework Guide

Eleventy image optimization guide

How to use Eleventy Image for responsive output, controlled widths, and manageable build performance in static publishing workflows.

Eleventy Image is powerful, but it exposes every decision. That makes this query a good pSEO candidate because the useful answer is not generic theory, it is exact configuration.

Best for

Static publishing teams using Eleventy

Default goal

Consistent transforms without custom glue everywhere

Watch closely

Width counts, cache behavior, and build time

Recommended setup

Keep the plugin configuration centralized and reuse it. Eleventy setups become messy when each shortcode, transform, or collection invents its own width and format rules.

  • Define a single width set per common layout class.
  • Use cache persistence for remote images if the build relies on them.
  • Prefer a small format set unless you have a clear reason to expand it.

Shared Eleventy Image configuration

import { eleventyImageTransformPlugin } from '@11ty/eleventy-img'

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    formats: ['avif', 'webp', 'jpeg'],
    widths: [480, 768, 1200],
    defaultAttributes: {
      sizes: '(min-width: 1024px) 1200px, 100vw',
      loading: 'lazy',
      decoding: 'async',
    },
  })
}

What to measure

  • Build duration before and after responsive width generation.
  • Cache hit rate for remote image transforms.
  • Whether the same image family is being transformed redundantly across templates.

Why it scales well as a page type

The Eleventy query is narrow and technical. A reusable page structure with exact config, caching advice, and pitfalls serves the intent directly.

Checklist

  • Centralize image plugin settings.
  • Keep width ladders short and intentional.
  • Persist cache where the deployment model allows it.
  • Use the same output policy across templates.

Common mistakes

  • Generating too many widths for a site that only has one or two actual content layouts.
  • Ignoring cache persistence and paying the build penalty every deploy.
  • Scattering image transforms across shortcodes without shared defaults.

Quick answers

What makes Eleventy image optimization harder than app frameworks?

You have more control and fewer guardrails. That is great for flexibility, but it means width strategy, caching, and output policy have to be designed intentionally.

How many widths should Eleventy generate?

Only enough to match the real layouts. More variants are not automatically better if the design only uses a few width ranges.