vite-imagetools

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

Features

• 🚀 Output modern formats
• 🖼 Resize Images
• 🔗 Easy Srcset generation
• ⚡️ Fast in development mode
• 🔒 Remove Image Metadata
• 🧩 Extensible

Read the docs to learn more!

Table of Contents

• Install
• Usage
• Options
• Contributing
• License

Install

npm install --save-dev vite-imagetools

Usage

import { defineConfig } from 'vite'
import { imagetools } from 'vite-imagetools'

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

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.

Options

defaultDirectives

• 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

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>

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

Record<string, OutputFormat>

---

extendTransforms

▸ 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>>[]

---

resolveConfigs

• Optional resolveConfigs: (entries: [string, string[]][], outputFormats: Record<string, 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>	-

Returns

Record<string, string | string[]>[]

An array of directive options

Contributing

Feel free to dive in! Open an issue or submit PRs! All information to get you started hacking on imagetools is in CONTRIBUTING.md!

License

MIT © Jonas Kruckenberg.