Image processing is practically required for today's performant internet, but pre-build scripts and complex CLIs are a pain. Processing images should be simple, so vite-image is!

vite-image relies on the image processing power of sharp and the ease-of-use of vitejs.

Installation

npm install --save-dev vite-image

Usage

vite.config.js

import image from 'vite-image'

export default {
    plugins: [ image() ]
}

Anywhere inside your project

import CoolImage from './custom-images/cool-image.jpg?width=300,600,900&blur=5'

Note

Boolean values can be shortened to just their key name, so ./img.jpg?flip is ./img.jpg?flip=true and ./img.jpg?!flip is ./img.jpg?flip=false.

Warning

Don't use your public folder to store images. Files kept there will be copied as-is to the server, unmodified by this plugin.

Examples

• Import an image.
• Resize to 400px, 700px, and 900px wide.
• Flip across the Y axis.

import DogImages from './images/dog.jpg?width=400,700,900&flip'

• Import an image.
• Resize like above.
• Only output src and width.
• Use TypedImage to describe the output type.

import type { TypedImage } from 'vite-image'
// A normal vite import as fallback.
import src from './images/dog.jpg'
// A special vite-image import.
import Images from './images/dog.jpg?width=400,700,900&export=src,width'

const srcset = (Images as TypedImage<'src' | 'width'>[])
    .map(img => `${img.src} ${img.width}w`)
    .join(', ')

Plugin Options

| Name | Default Value | Description | | :---: | --- | --- | | include | '**/*.{heic,heif,avif,jpeg,jpg,png,tiff,webp,gif}?*' | A picomatch pattern to match images against. | | exclude | '' | Another picomatch pattern, this time excluding images. | | deliminator | , | The character used to split multiple values in a query. | | transformers | [] | User-specified custom image transformers. | | default_exports | ['src', 'aspect', 'width', 'height', 'format'] | By default, vite-image exports these 5 image attributes. More attributes can be found here. (Scroll down to "info contains the output image") |

Default Transformers

To learn about default transformers, click here

Return Type

vite-image will return a modified sharp instance, trimmed down for the web. 3 extra values are included: aspect (width / height), src (an href pointing to the image), and transformers (an array of the transformers applied to the image).

Without any configuration, five values will be returned: src, aspect, width, height, and format.

There are two ways to modify what's returned:

1. Change config.default_exports (changes settings project-wide).
2. Add a export input, like image?export=width,height,src. (This will override whatever's in your config.default_exports)

Try to trim down your exports to only what's necessary to keep your bundle as small as possible!

Typescript

To help developers using TypeScript, an easy helper type is included. To use it, just import and supply keys:

import type { TypedImage } from 'vite-image'

import CustomImages from './images/cool-image?width=500,800,1000&export=width,src'

// Properly typing the import isn't possible as far as I know, but this works well enough.
for (const image of CustomImages as TypedImage<'width' | 'src'>)
{
    console.log('src:', image.src)
    console.log('width:', image.width)
}

If you are developing a transformer, the transformer type is also supplied, and can be extended.

import type { Transformer } from 'vite-image'

export default {
    name: 'test-transformer',
    matcher: (config) => typeof config['foo'] === 'boolean' && typeof config['bar'] === 'string',
    transform: (img, config) => {
        if (config['foo'])
            return img.withMetadata({
                exif: {
                    IFD0: {
                        Copyright: config['bar']
                    }
                }
            })
        return img
    }
} as Transformer<'foo' | 'bar', { foo: boolean, bar: string }>

Final Notes

If on Linux, jemalloc will improve image processing times by enabling concurrent operations. This stackoverflow answer explains how to install and use jemalloc.

Contributing

For small changes, feel free to open a pull request and solve whatever issue is plaguing you.

For larger changes (API breaking), please file an issue describing what changes should be made and why.

Acknowledgments

This project is based on the work done over at vite-imagetools. Many small features (like the dev mode) were inspired by Jonas' work.