Skip to content
@staticbolt/core

Convert Image Plugin

A staticbolt plugin that converts images to a target format at build time using sharp. It also rewrites every reference to those images in your HTML, scripts, and manifests so they point at the converted files. During development, images are served in their original format and nothing is converted.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { convertImagePlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [convertImagePlugin()],
});

By default the plugin converts all .jpg, .jpeg, and .png files under sources/assets/ to WebP.

Every matched image is registered as a binary asset before the transforms run, with the converted path as its output path. The write files plugin copies the original under that path, and the conversion overwrites it after the build. That keeps the copy assets plugin from copying the original. It also lets the cache bust plugin version the converted file like any other output.

Per-file quality and preset overrides

You can override the quality and preset for a single image by putting the values in its filename, without changing the configuration.

To set a custom quality, append -q:{value} to the filename before the extension.

photo-q:80.jpg     -> converted at quality 80
banner-q:60.png    -> converted at quality 60

To set a custom preset, append -p:{preset} to the filename.

illustration-p:drawing.png   -> converted using the "drawing" preset
portrait-p:photo.jpg         -> converted using the "photo" preset

Both can be combined.

hero-q:75-p:picture.jpg

Plugin Options

format

  • Type: "webp" | "avif" | "png" | "jpeg"
  • Default: "webp"

The output format that every matched image is converted to.

convertImagePlugin({
  format: "avif",
});

quality

  • Type: number (1-100)
  • Default: 100

The default output quality for every converted image. The filename convention described above overrides it per file.

convertImagePlugin({
  quality: 80,
});

preset

  • Type: "default" | "photo" | "picture" | "drawing" | "icon" | "text"
  • Default: "default"

The default compression preset. It only applies to WebP output. The filename convention described above overrides it per file.

convertImagePlugin({
  preset: "photo",
});

include

  • Type: string[]
  • Default: ["sources/assets/**/*.{jpg,jpeg,png}"]

Glob patterns for the image files to convert.

convertImagePlugin({
  include: ["src/images/**/*.{jpg,jpeg,png}"],
});

exclude

  • Type: string[]
  • Default: []

Glob patterns for files to skip during conversion.

convertImagePlugin({
  exclude: ["sources/assets/originals/**"],
});