Vite-plugin-imageset NPM

vite-plugin-imageset :toolbox:

A toolbox of custom import directives that can transform your image at compile-time. All of the image transformations are powered by sharp.

Install

With npm:

npm install --dev vite-plugin-imageset

Or with yarn:

yarn add --dev vite-plugin-imageset

Usage

Add the plugin to your vite config:

import imageset from 'vite-plugin-imageset'

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

The you can use all the directives when importing image files:

<!-- This will transcode the image into webp-->
<img src="../assets/example.jpg?webp">

<!-- This resizes the image to be width x height pixels -->
<img src="../assets/example.jpg?size=500x300">

You can specify any number of directives to customize almost any aspect of the image:

<img src="../assets/example.jpg?size=1200x900&fit=cover&position=top?webp">

This for example will resize the image to 1200x900 pixels, using the object-fit cover and keeping the top of the image in view. It will also produce a webp image from the jpeg source.

You can of course also import images from javascript like so:

import Image from 'example.jpg?format=avif'

Options

All plugin options are optional.

`include`

Type: string | RegExp | Array<string | RegExp> Default: ['**/*.jpg', '**/*.jpg', '**/*.png', '**/*.webp', '**/*.webp', '**/*.avif', '**/*.gif', '**/*.heif']

Which files to include when processing.

`exclude`

Type: string | RegExp | Array<string | RegExp> Default: ['public/**/*']

Which files to exclude when processing. By default this excludes vites public folder to match the default behavior.

Directives

vite-plugin-imagset works on a directive based workflow where you specify what transformation to apply in the import statement. A Directive is basically a querystring field followed by an optional argument like you have seen above.

example.jpg?directive=argument

Commonly used directives also expose Shorthands. Shorthands have no arguments.

example.jpg?shorthand

A good example for shorthands is the format directive

Directives can depend on other directives and some my be incompatible with others. Directives can also be composed into more complex directives. (The size directive is a good example, it is composed from the width and height directives). See the contributing section for details.

Below is the list of all directives shipped by default:

`width`

Argument: <number> Resizes the image to have a with of width pixels. If not set, the height will be scaled automatically to match the width.

You cannot use with and size together.

`height`

Argument: <number> Resize the image to have a height of height pixels. If not set, the width will be scaled automatically to match the height.

You cannot use height and size together.

`size`

Argument: <number>x<number> Sets width and height of the image simultaneously.

When using size you cannot set width or heighton the same resource.

`fit`

Argument: <'cover' | 'contain' | 'fill' | 'inside' | 'outside'> How the image should be resized when both width and height are given. If only one is specified this has no effect since the missing side will be scaled to keep the aspect ratio. The default behavior when resizing is cover.

Shorthands

cover
contain
fill
inside
outside

`position`

Shorthands

top
right top
right
right bottom
bottom
left bottom
left
left top
north
northeast
east
southeast
south
southwest
west
northwest
center
entropy
`attention

`kernel`

Argument: <'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3'> The interpolation kernel to use when resizing the image, the default value is lanczos3.

`format`

Some of these formats my not be available on your platform/setup

Optionally you can use one of the Shorthands below like so:

<!-- instead of -->
<img src="example.jpg?format=webp">
<!-- you can write -->
<img src="example.jpg?webp">

Shorthands:

jpeg
jpg
webp
avif
png
gif
tiff
heif

`rotate`

TODO

`flip`

TODO

`flop`

TODO

`sharpen`

TODO

`blur`

TODO

`median`

TODO

`flatten`

TODO

`gamma`

TODO

`invert`

TODO

`normalize`

TODO

Contributing

Saw a TODO somewhere above? Chances are these are features I didn't have time for yet, so if you want this feature to be implemented have a look at the custom directive section below. PRs are very welcome!

See the contributing file!