A toolbox of custom import directives that can transform your image at compile-time. All of the image transformations are powered by sharp.
With npm:
npm install --dev vite-plugin-imageset
Or with yarn:
yarn add --dev vite-plugin-imageset
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'
All plugin options are optional.
Type: string | RegExp | Array<string | RegExp>
Default: ['**/*.jpg', '**/*.jpg', '**/*.png', '**/*.webp', '**/*.webp', '**/*.avif', '**/*.gif', '**/*.heif']
Which files to include when processing.
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.
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:
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
andsize
together.
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
andsize
together.
Argument: <number>x<number>
Sets width and height of the image simultaneously.
When using
size
you cannot setwidth
orheight
on the same resource.
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
Argument: < 'top' |
'right top' |
'right' |
'right bottom' |
'bottom' |
'left bottom' |
'left' |
'left top' |
'north' |
'northeast' |
'east' |
'southeast' |
'south' |
'southwest' |
'west' |
'northwest' |
'center' |
'entropy' |
'attention'>
When fit is cover
or contain
you can specify where the image should be anchored.
The behavior is similar to the css object-postion property.
For further details on the two special values entropy
& attention
see the sharp documentation
Shorthands
top
right top
right
right bottom
bottom
left bottom
left
left top
north
northeast
east
southeast
south
southwest
west
northwest
center
entropy
- `attention
Argument: <'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3'>
The interpolation kernel to use when resizing the image, the default value is lanczos3
.
Argument: <'jpeg' | 'jpg' | 'webp' | 'avif' | 'png' | 'gif' | 'tiff' | 'heif'>
Transcodes the image to the give format. This directive will always be applied last.
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
TODO
TODO
TODO
TODO
TODO
TODO
TODO
TODO
TODO
TODO
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!
TODO