vite-imagetools

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.