Load and transform images using a toolbox of import directives!
npm install vite-imagetools!npm (latest)
A toolbox of import directives for Vite that can transform
your image at compile-time. All of the image transformations are powered by sharp.
- 🚀 Output modern formats
- 🖼 Resize Images
- 🔗 Easy Srcset generation
- ⚡️ Fast in development mode
- 🔒 Remove Image Metadata
- 🧩 Extensible
> Read the docs to learn more!
- Install
- Usage
- Options
- Contributing
- License
``
npm install --save-dev vite-imagetools
`ts
import { defineConfig } from 'vite'
import { imagetools } from 'vite-imagetools'
export default defineConfig({
plugins: [imagetools()]
})
`
`js`
import Image from 'example.jpg?w=400&h=300&format=webp'
You can also import a directory of images using
Vite's import.meta.glob with its query option.
• Optional defaultDirectives: URLSearchParams | (url: URL) => URLSearchParams
This option allows you to specify directives that should be applied _by default_ to every
image. You can also provide a function, in which case the function gets passed the asset ID and should return an object
of directives. This can be used to define all sorts of shorthands or presets.
example
`js
import { defineConfig } from 'vite'
import { imagetools } from 'vite-imagetools'
export default defineConfig({
plugins: [
imagetools({
defaultDirectives: (url) => {
if (url.searchParams.has('spotify')) {
return new URLSearchParams({
tint: 'ffaa22'
})
}
return new URLSearchParams()
}
})
]
})
`
---
• exclude: string | RegExp | (string | RegExp)[]
What paths to exclude when processing images. This defaults to the public dir to mirror Vite's behavior.
default 'public\/*\/'
---
• include: string | RegExp | (string | RegExp)[]
Which paths to include when processing images.
default /^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/
---
• removeMetadata: boolean
Wether to remove potentially private metadata from the image, such as exif tags etc.
default true
---
▸ Optional extendOutputFormats(builtins): Record<string,OutputFormat\>
You can use this option to extend the builtin list of output formats. This list will be merged with the builtin output
formats before determining the format to use.
default []
#### Parameters
| Name | Type |
| :--------- | :-------------------------------------------------------------------------------------- |
| builtins | Record<string, OutputFormat\> |
#### Returns
---
▸ Optional extendTransforms(builtins):TransformFactory<Record<string, unknown\>\>[]
You can use this option to extend the builtin list of import transforms. This list will be merged with the builtin
transforms before applying them to the input image.
default []
#### Parameters
| Name | Type |
| :--------- | :------------------------------------------------------------------------------------------------------------ |
| builtins | TransformFactory<Record<string, unknown\>\>[] |
#### Returns
TransformFactory<Record<string, unknown\>\>[]
---
• Optional resolveConfigs: (entries: [string, string[]][], outputFormats: Record<string,OutputFormat\>) => Record
#### Type declaration
▸ (entries, outputFormats): Record
This function builds up all possible combinations the given entries can be combined an returns it as an array of objects
that can be given to a the transforms.
##### Parameters
| Name | Type | Description |
| :-------------- | :------------------------------------------------------------------------ | :------------------------ |
| entries | [string, string[]][] | The url parameter entries |outputFormats
| | Record<string, OutputFormat\> | - |
##### Returns
Record
An array of directive options
Feel free to dive in! Open an issue or submit PRs! All
information to get you started hacking on imagetools is in CONTRIBUTING.md!