vite-imagetools
Version:
Load and transform images using a toolbox of import directives!
196 lines (125 loc) • 6.08 kB
Markdown
# vite-imagetools
<!-- badges -->
[](https://github.com/RichardLitt/standard-readme)
[](https://codecov.io/gh/JonasKruckenberg/imagetools/)
A toolbox of import [directives](../../docs/directives.md) for [Vite](https://github.com/vitejs/vite) that can transform
your image at compile-time. All of the image transformations are powered by [sharp](https://sharp.pixelplumbing.com).
## Features
- **🚀 Output modern formats**
- **🖼 Resize Images**
- **🔗 Easy Srcset generation**
- **⚡️ Fast in development mode**
- **🔒 Remove Image Metadata**
- **🧩 Extensible**
> [Read the docs to learn more!](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/README.md)
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Options](#options)
- [Contributing](#contributing)
- [License](#license)
## Install
```
npm install --save-dev vite-imagetools
```
## Usage
```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](https://vitejs.dev/guide/features.html#custom-queries).
## Options
### defaultDirectives
• `Optional` **defaultDirectives**: `URLSearchParams | (url: URL) => URLSearchParams`
This option allows you to specify [directives](../../docs/directives.md) 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](../../docs/directives.md). 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
• **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
• **include**: `string | RegExp | (string | RegExp)[]`
Which paths to include when processing images.
**`default`** `/^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/`
---
### removeMetadata
• **removeMetadata**: `boolean`
Wether to remove potentially private metadata from the image, such as exif tags etc.
**`default`** true
---
### extendOutputFormats
▸ `Optional` **extendOutputFormats**(`builtins`): `Record`<`string`,
[`OutputFormat`](../../docs/core/src/type-aliases/OutputFormat.md)\>
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`](../../docs/core/src/type-aliases/OutputFormat.md)\> |
#### Returns
`Record`<`string`, [`OutputFormat`](../../docs/core/src/type-aliases/OutputFormat.md)\>
---
### extendTransforms
▸ `Optional` **extendTransforms**(`builtins`):
[`TransformFactory`](../../docs/core/src/type-aliases/TransformFactory.md)<`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`](../../docs/core/src/type-aliases/TransformFactory.md)<`Record`<`string`, `unknown`\>\>[] |
#### Returns
[`TransformFactory`](../../docs/core/src/type-aliases/TransformFactory.md)<`Record`<`string`, `unknown`\>\>[]
---
### resolveConfigs
• `Optional` **resolveConfigs**: (`entries`: `[string, string[]][]`, `outputFormats`: `Record`<`string`,
[`OutputFormat`](../core/src/README.md#outputformat)\>) => `Record<string, string | string[]>[]`
#### Type declaration
▸ (`entries`, `outputFormats`): `Record<string, string | string[]>[]`
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`](../core/src/README.md#outputformat)\> | - |
##### Returns
`Record<string, string | string[]>[]`
An array of directive options
## Contributing
Feel free to dive in! [Open an issue](https://github.com/JonasKruckenberg/imagetools/issues/new) or submit PRs! All
information to get you started hacking on imagetools is in [CONTRIBUTING.md](../../CONTRIBUTING.md)!
## License
[MIT © Jonas Kruckenberg.](./LICENSE)