imagetools

Imagetools is a toolbox of import directives designed to transform and optimize images at compile-time. It leverages sharp to perform high-performance image processing.

Key capabilities include:

• Outputting modern image formats.
• Resizing images.
• Generating srcset attributes easily.
• Fast performance during development.
• Removing image metadata for privacy and optimization.
• Extensible architecture for custom transformations.

The vite/src directory contains the core logic and type definitions for the imagetools integration within Vite. It provides a comprehensive set of interfaces, type aliases, variables, and functions used to manipulate images via URL parameters or configuration.

Key areas of the API include:

• Interfaces: Definitions for transformation options such as ResizeOptions, BlurOptions, FormatOptions, and RotateOptions.
• Type Aliases: Core types like ImageTransformation, OutputFormat, and ImageConfig.
• Functions: Core logic including applyTransforms, generateTransforms, getMetadata, and parseURL.
• Variables: Predefined transformation values and helper functions like resize, blur, grayscale, and format.

Instead of manually resizing and exporting images in tools like Photoshop, imagetools allows you to perform image transformations directly within your code via import queries. By appending transformation parameters to an image import path, the tool automatically handles the resizing and optimization during the build process. This ensures that images are served at the correct dimensions and file sizes, improving SEO and reducing data costs for users.

import Image from 'example.jpeg?w=300&h=400'

You can generate multiple variations of an image from a single import statement by providing a semicolon-separated list of values for a directive.

If you combine multiple directives with multiple arguments, imagetools will generate a combination for every possible pair. For example, ?w=300;500&format=webp;avif will generate 4 images (300w/webp, 300w/avif, 500w/webp, 500w/avif).

// Generates three images with widths of 300, 500, and 700 pixels
import Image300 from 'example.jpg?w=300;500;700'

// Generates 9 different images (3 widths x 3 formats)
import Images from 'example.jpg?w=300;500;700&format=webp;avif;jpg'

A Directive (also known as a TransformFactory) is a function that takes a configuration object and a context object, and returns either an ImageTransformation function or undefined.

Directives are responsible for parsing incoming arguments (which are strings) and determining if a transformation should be applied. If the transformation is applicable, you must return a function that accepts a sharp instance and returns the transformed image.

To reuse existing directives, import them from imagetools and invoke them within your factory, ensuring you pass the ctx (context) object so that warnings and keyword usage tracking work correctly.

type TransformFactory<A = {}> = (
  metadata: Partial<ImageConfig & A>,
  ctx: TransformFactoryContext
) => ImageTransformation | undefined

The OutputFormat type defines the structure of the function returned by an image import in imagetools. It is a higher-order function that follows a two-step execution pattern:

1. Initialization: You call the function with an optional array of strings (args?).
2. Execution: The resulting function is then called with an array of ProcessedImageMetadata objects, which finally returns the actual image data (of type unknown).

This pattern allows the image import to be configured with specific arguments before the metadata from the processing pipeline is injected to produce the final output.

// Conceptual representation of the OutputFormat signature
type OutputFormat = (args?: string[]) => (metadata: ProcessedImageMetadata[]) => unknown;

Instead of manually resizing and exporting images in external editors, imagetools allows you to perform image transformations directly within your code using URL query parameters in the import statement. This automates the process of resizing and optimizing images during the build step, ensuring you serve the correct dimensions and reducing page weight.

import Image from 'example.jpeg?w=300&h=400'

Imagetools supports specific output directives that change how the processed image information is returned. Instead of just a URL, you can request different data structures:

• metadata: Returns the image metadata.
• picture: Returns a <picture> element structure.
• srcset: Returns a srcset string.
• url: Returns the image URL.

To use Imagetools in a Vite project, install the vite-imagetools package as a development dependency using npm.

npm install --save-dev vite-imagetools

You can transform images by appending directives as query parameters to the image import URL. You can specify multiple key-value pairs to invoke all specified directives simultaneously.

import Image from 'example.jpg?w=400&h=300&format=webp'

To use vite-imagetools in your project, add the imagetools plugin to your vite.config.ts (or .js) file using defineConfig.

import { defineConfig } from 'vite'
import { imagetools } from 'vite-imagetools'

export default defineConfig({
  plugins: [imagetools()]
})