@squoosh-kit/vite-plugin

A Vite plugin for Squoosh-Kit that handles asset copying and WebAssembly configuration.

Overview

The @squoosh-kit/vite-plugin simplifies integrating Squoosh-Kit codecs into Vite projects by:

• Automatically copying browser-compatible assets from @squoosh-kit/webp and @squoosh-kit/resize packages
• Configuring WASM module handling with proper MIME types and CORS headers
• Setting up optimized dependency exclusions to prevent bundling of heavy WASM modules
• Providing WASM file serving with correct headers in development mode

Installation

bun add -D @squoosh-kit/vite-plugin
# or
npm install --save-dev @squoosh-kit/vite-plugin

Quick Start

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import squooshVitePlugin from '@squoosh-kit/vite-plugin';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react(), squooshVitePlugin(resolve('node_modules/@squoosh-kit'))],
});

That's it! The plugin will:

1. Copy Squoosh-Kit browser assets to your public/squoosh-kit directory
2. Configure Vite to properly handle WASM files
3. Set necessary CORS headers for cross-origin embedder policy
4. Exclude heavy dependencies from optimization

Worker mode (including auto in the browser) loads those assets from /squoosh-kit by default. You only need to pass assetPath if you serve them from a different URL.

What the Plugin Does

Asset Copying

The plugin automatically copies:

• Browser builds (.browser.mjs only — sourcemaps are not copied or published)
• WASM modules (.wasm files and supporting JavaScript)

From both @squoosh-kit/webp and @squoosh-kit/resize to public/squoosh-kit/.

WASM Configuration

The plugin:

• Sets correct MIME type (application/wasm) for .wasm files
• Configures CORS headers:
  • Cross-Origin-Embedder-Policy: credentialless
  • Cross-Origin-Opener-Policy: same-origin
• Ensures WASM files are treated as assets
• Handles WASM file paths correctly in both development and production

Development Server

In development mode, the plugin:

• Serves WASM files with proper headers
• Handles multiple path variants (e.g., ./wasm/ vs ../wasm/)
• Correctly resolves @squoosh-kit/wasm/ imports

Usage Example

After setting up the plugin, factories default to auto mode (workers in the browser):

import { webp, resize } from '@squoosh-kit/core';

const encoder = webp.createWebpEncoder();
const resizer = resize.createResizer();

const resizedImage = await resizer(imageData, { width: 800 });
const webpData = await encoder(resizedImage, { quality: 80 });

Override assetPath only if you serve the copied assets from a different public URL:

const encoder = webp.createWebpEncoder('auto', {
  assetPath: '/custom-assets/squoosh-kit',
});

API Reference

squooshVitePlugin(squooshKitRoot)

Returns a Vite plugin that configures Squoosh-Kit integration.

Parameters:

• squooshKitRoot: string — Path to the @squoosh-kit directory inside node_modules. The plugin uses this to locate the webp/dist and resize/dist directories for asset copying.

Returns: Vite Plugin

Example:

import squooshVitePlugin from '@squoosh-kit/vite-plugin';
import { resolve } from 'path';

export default defineConfig({
  plugins: [squooshVitePlugin(resolve('node_modules/@squoosh-kit'))],
});

How It Works

Build Process

1. buildStart hook: Copies assets from package distributions to public/squoosh-kit/
2. config hook: Injects Vite configuration for WASM handling and optimization
3. configureServer hook: Sets up development middleware for WASM file serving

Asset Paths

Assets are copied to predictable locations:

public/
└── squoosh-kit/
    ├── webp/
    │   ├── index.browser.mjs
    │   ├── index.d.ts
    │   └── wasm/
    │       ├── webp_enc.js
    │       ├── webp_enc.wasm
    │       └── ... (other WASM files)
    └── resize/
        ├── index.browser.mjs
        ├── index.d.ts
        └── wasm/
            ├── squoosh_resize.js
            ├── squoosh_resize.wasm
            └── ... (other WASM files)

In development, these are served from http://localhost:5173/squoosh-kit/. In production, they're available at /squoosh-kit/.

Configuration

The plugin copies assets to public/squoosh-kit/. Auto mode (the default) uses workers in the browser and loads from /squoosh-kit.

Override the public URL only when needed:

createWebpEncoder('auto', { assetPath: '/custom-assets/squoosh-kit' });

Troubleshooting

"Cannot find module @squoosh-kit/webp"

Ensure the packages are installed:

bun add @squoosh-kit/webp @squoosh-kit/resize

WASM files not loading

Check that:

1. The plugin is configured before other plugins
2. Worker assets are reachable at /squoosh-kit/ (or the assetPath you passed)
3. Your server headers allow CORS (plugin should set these automatically)

Build fails with "dist not found"

Ensure you've built the Squoosh-Kit packages first:

bun run build

Performance Tips

• The plugin runs once during Vite startup
• Asset copying adds < 100ms to build time
• WASM files are excluded from Vite's optimization pipeline
• Consider using auto mode (default) for long-running image processing in the browser

Architecture

The plugin follows Squoosh-Kit principles:

• Minimal and focused: Handles only WASM and asset configuration
• Framework agnostic: Works with any Vite-based framework
• Well-typed: Full TypeScript support
• Performance conscious: Lazy loading of WASM modules

License

MIT - part of the Squoosh-Kit family