@codestitchofficial/eleventy-plugin-sharp-images N

eleventy-plugin-sharp-images

An Eleventy plugin that brings the full capabilities of Sharp to your static sites, optimizing assets and improving website performance. Brought to you by CodeStitch!

This plugin is a continuation of the now-abandoned eleventy-plugin-sharp by luwes.

Features

Full Sharp integration, allowing for cropping, resizing, compressing, manipulating, and changing file types within your Eleventy project
Efficient caching mechanism to prevent regeneration of identical images within and between builds, both locally and when deployed to Netlify
Asynchronous processing - even when using non-asynchronous features (like Nunjucks Macros)

Installation

Install the plugin:

npm install @codestitchofficial/eleventy-plugin-sharp-images

Configure Eleventy:

const eleventyPluginSharpImages = require("@codestitchofficial/eleventy-plugin-sharp-images");

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginSharpImages, {
        urlPath: "/assets/images",
        outputDir: "public/assets/images",
    });
};

Important: This plugin relies on specific HTML comments to process images. If these comments are removed or altered by minification before this plugin runs, it will cause errors. To prevent this, make sure to add any HTML minification plugins after this plugin in your Eleventy configuration file. This ensures that image processing occurs before any minification takes place.

For caching (Netlify use only), install Netlify's caching plugin:

npm install netlify-plugin-cache

Add caching configuration to netlify.toml in the root of your repository:

[[plugins]]
package = "netlify-plugin-cache"

  [plugins.inputs]
  paths = [
    "public/assets/images", # Processed images - adjust to match your outputDir
    ".cache" # Remote Assets
  ]

Configuration

Only two options are needed to configure the plugin:

urlPath: The prefix for generated image URLs in your built site
outputDir: The directory where processed images should be saved

Usage

The plugin works by using the {% getUrl %} shortcode, supplying an image URL, and chaining filters that correspond to Sharp's transformation options:

<picture>
    <source srcset="{% getUrl "/assets/images/image.jpg" | resize({ height: 50, width: 50 }) | avif %}" media="(max-width: 600px)" type="image/avif"> <source srcset="{% getUrl
    "/assets/images/image.jpg" | resize({ height: 50, width: 50 }) | webp %}" media="(max-width: 600px)" type="image/webp"> <source srcset="{% getUrl "/assets/images/image.jpg" |
    resize({ height: 400, width: 400 }) | jpeg %}" media="(min-width: 601px)" type="image/jpeg"> <img src="{% getUrl "/assets/images/image.jpg" | resize({ height: 400, width: 400
    }) | jpeg %}" alt="Description of the image">
</picture>

In this example, we set up responsive image HTML with three <source> elements. Each source generates an image from /assets/images/image.jpg, using the resize filter to crop the image to specific dimensions, before outputting the image in AVIF, WebP, or JPEG format.

The processed image is then cached to prevent unnecessary regeneration.

Each Sharp transformation can be used as a filter, with options passed as an object. For example, to adjust the image position during resizing:

{% getUrl "/assets/images/image.jpg" | resize({ height: 50, width: 50, position: "top" }) | avif %}

Examples

Resize image to set dimensions:

{% getUrl "/assets/images/image.jpg" | resize({ height: 50, width: 50 }) %}

Resize image to set dimensions and convert to AVIF, with a quality value of 75:

{% getUrl "/assets/images/image.jpg" | resize({ height: 50, width: 50 }) | avif({ quality: 75 }) %}

Resize image to set dimensions, cropped to the area of interest, and convert to AVIF:

{% getUrl "/assets/images/image.jpg" | resize({ height: 50, width: 50, position: "attention" }) | avif %}

Rotate an image 90 degrees and convert it to grayscale:

{% getUrl "/assets/images/image.jpg" | rotate(90) | grayscale %}

How It Works

To support environments where async features aren't allowed (like processing an image in a Nunjucks Macro), the shortcode doesn't directly generate the image. Instead, it creates a comment with a JSON configuration object. At the end of an Eleventy build, a Transform uses a regex to find all instances of these comments and process the images.

The configuration is hashed, and the file is renamed to include this hash. If an image path or its transformations change, the hash/filename will change, invalidating the cache. This works with netlify-plugin-cache to prevent reprocessing between builds in a live environment.