use-squoosh

中文文档

Lightweight browser image converter powered by Squoosh WASM. Zero runtime dependencies with codecs loaded on-demand from CDN.

Features

• Zero Dependencies - Codecs are dynamically loaded from CDN when needed
• Format Support - Convert between PNG, JPEG, and WebP
• Quality Control - Adjustable compression quality for JPEG/WebP
• Smart Caching - Codec caching with race condition prevention
• TypeScript - Full type definitions included
• Tree Shakable - ESM, CJS, and UMD builds available

Installation

npm install use-squoosh

Quick Start

import { convert, pngToWebp, compress } from 'use-squoosh';

// Convert PNG to WebP
const webpBuffer = await pngToWebp(pngFile, { quality: 80 });

// Generic conversion
const result = await convert(imageFile, {
  from: 'png',
  to: 'webp',
  quality: 85
});

// Compress image (keep format)
const compressed = await compress(imageFile, {
  format: 'jpeg',
  quality: 70
});

API

Conversion Functions

convert(input, options)

Convert image between formats.

const result = await convert(input, {
  from: 'png',    // Source format (auto-detected for Blob/File)
  to: 'webp',     // Target format (default: 'webp')
  quality: 80     // 0-100, for JPEG/WebP only
});

pngToWebp(input, options?)

const webp = await pngToWebp(pngFile, { quality: 80 });

jpegToWebp(input, options?)

const webp = await jpegToWebp(jpegFile, { quality: 80 });

webpToPng(input)

const png = await webpToPng(webpFile);

webpToJpeg(input, options?)

const jpeg = await webpToJpeg(webpFile, { quality: 85 });

compress(input, options?)

Compress image while keeping the same format.

const compressed = await compress(imageFile, {
  format: 'webp',
  quality: 75
});

Low-Level Functions

decode(buffer, format)

Decode image buffer to ImageData.

const imageData = await decode(buffer, 'png');

encode(imageData, format, options?)

Encode ImageData to specified format.

const buffer = await encode(imageData, 'webp', { quality: 80 });

Utility Functions

toBlob(buffer, type?)

Convert ArrayBuffer to Blob.

const blob = toBlob(buffer, 'image/webp');

toDataURL(buffer, type?)

Convert ArrayBuffer to Data URL.

const dataUrl = await toDataURL(buffer, 'image/webp');

download(buffer, filename?, type?)

Trigger browser download.

download(buffer, 'image.webp', 'image/webp');

getFormat(mimeOrExt)

Get format from MIME type or extension.

getFormat('image/png');  // 'png'
getFormat('jpg');        // 'jpeg'

Configuration

configure(config)

Customize CDN and codec versions.

import { configure } from 'use-squoosh';

// Use unpkg instead of jsDelivr
configure({ baseUrl: 'https://unpkg.com' });

// Use specific versions
configure({
  webpVersion: '1.5.0',
  pngVersion: '3.1.1',
  jpegVersion: '1.6.0'
});

// Custom cache key (for multiple instances)
configure({ cacheKey: '__MyAppImageCache__' });

// Use self-hosted CDN
configure({ baseUrl: 'https://your-cdn.com/npm' });

Self-hosted CDN Requirements:

The library loads codecs from URLs following this pattern:

{baseUrl}/@jsquash/{format}@{version}/{file}

For example:

https://your-cdn.com/npm/@jsquash/webp@1.5.0/encode.js
https://your-cdn.com/npm/@jsquash/png@3.1.1/decode.js

To self-host, ensure your CDN mirrors the @jsquash package structure:

your-cdn.com/npm/
  @jsquash/
    webp@1.5.0/
      encode.js
      decode.js
    png@3.1.1/
      encode.js
      decode.js
    jpeg@1.6.0/
      encode.js
      decode.js

getConfig()

Get current configuration.

const config = getConfig();

resetConfig()

Reset to default configuration.

resetConfig();

Preloading & Cache

preload(formats?)

Preload codecs for faster first conversion.

// Preload all formats
await preload();

// Preload specific formats
await preload(['webp', 'png']);

isLoaded(format)

Check if a format's codecs are loaded.

if (isLoaded('webp')) {
  // WebP encoder and decoder are ready
}

getLoadedStatus()

Get loading status for all formats.

const status = getLoadedStatus();
// { webp: { encoder: true, decoder: true }, png: {...}, jpeg: {...} }

clearCache()

Clear all cached codecs.

clearCache();

Browser Support

Requires browsers with WebAssembly support:

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

How It Works

This library uses @jsquash codecs (based on Google's Squoosh) loaded dynamically from CDN. On first use of each format, the corresponding encoder/decoder WASM module is fetched and cached.

Default CDN: https://cdn.jsdelivr.net/npm

License

MIT