How to add custom directive to enhanced-img?

[gterras]

Hi,

I'm trying to add custom directive to enhanced-img / vite-imagetools:

const toGreyscale: TransformFactory = (image) => {
  return image.greyscale()
}

export default defineConfig({
	plugins: [
		enhancedImages(),
		imagetools({
			extendTransforms: (builtins) => [toGreyscale, ...builtins],
		}),
		sveltekit(),
	],
})

// in component: 
import Pic from 'img.jpeg?enhanced&toGreyscale=1'

This doesnt do anything, and 500 if the imagetools plugin is passed before enhancedImages. I can't find anything in the docs, am I missing something?

Thanks

[Maxaubert]

This isn't supported today, and it's not a mistake on your side.

Cause: enhancedImages() builds and owns its own private vite-imagetools plugin instance internally, with a hardcoded defaultDirectives function, and there is no option to pass extendTransforms (or anything else) into that internal instance:

kit/packages/enhanced-img/src/index.js

Lines 8 to 59 in c6f9a78

	export function enhancedImages() {
	const imagetools_instance = imagetools_plugin();
	return !process.versions.webcontainer
	? [image_plugin(imagetools_instance), imagetools_instance]
	: [];
	}
	/**
	* @param {import('sharp').Metadata} meta
	* @returns {string}
	*/
	function fallback_format(meta) {
	if (meta.pages && meta.pages > 1) {
	return meta.format === 'tiff' ? 'tiff' : 'gif';
	}
	if (meta.hasAlpha) {
	return 'png';
	}
	return 'jpg';
	}
	function imagetools_plugin() {
	/** @type {Partial<import('vite-imagetools').VitePluginOptions>} */
	const imagetools_opts = {
	defaultDirectives: async ({ pathname, searchParams: qs }, metadata) => {
	if (!qs.has('enhanced')) return new URLSearchParams();
	const meta = await metadata();
	const img_width = qs.get('imgWidth');
	const width = img_width ? parseInt(img_width) : meta.width;
	if (!width) {
	console.warn(`Could not determine width of image ${pathname}`);
	return new URLSearchParams();
	}
	const { widths, kind } = get_widths(width, qs.get('imgSizes'));
	return new URLSearchParams({
	as: 'picture',
	format: `avif;webp;${fallback_format(meta)}`,
	w: widths.join(';'),
	...(kind === 'x' && !qs.has('w') && { basePixels: widths[0].toString() })
	});
	},
	namedExports: false
	};
	// TODO: should we make formats or sizes configurable besides just letting people override defaultDirectives?
	// TODO: generate img rather than picture if only a single format is provided
	// by resolving the directives for the URL in the preprocessor
	return imagetools(imagetools_opts);
	}

The imagetools() you add separately in vite.config is a completely different plugin object. Its extendTransforms only applies to transforms that plugin instance resolves, but ?enhanced images are always resolved by enhancedImages()'s own internal instance, which never sees your custom transform. That's why toGreyscale=1 is silently ignored, and why the two imagetools plugin instances collide (hence the 500) when you put your own imagetools() before enhancedImages() in the plugin list, since they end up racing to handle the same id.

There's no current workaround to inject a custom directive into the ?enhanced pipeline specifically.

For what it's worth, this exact gap (custom defaultFormats/defaultWidths and an imagetools: VitePluginOptions passthrough, which would let you do enhancedImages({ imagetools: { extendTransforms } })) was actually implemented and merged in #15354, but got reverted four days later in #16122 over unresolved design concerns. #16124 is an open placeholder to bring it back once those are settled, but it hasn't landed.

If you need a custom transform like greyscale today, your practical option is to skip ?enhanced/<enhanced:img> for those images and use plain imagetools directives yourself (e.g. img.jpeg?toGreyscale=1&w=400;800&format=avif;webp;jpg&as=picture), building the <picture> markup by hand instead of relying on the enhanced-img preprocessor.