@squoosh-kit/mozjpeg

Squoosh-Kit

Squoosh-Kit is built on a simple idea: provide a lightweight and modular bridge to the powerful, production-tested codecs from Google's Squoosh project. This package (@squoosh-kit/mozjpeg) is one of those modules.

Directly from the Source We don't modify the core MozJPEG codec. The WebAssembly (.wasm) binary is taken directly from the official Squoosh repository builds. This means you get the exact same performance, quality, and reliability you'd expect from Squoosh.

A Thin, Modern Wrapper Our goal is to provide a minimal, modern JavaScript wrapper around the codec. We handle the tricky parts—like loading WASM, managing web workers, and providing a clean, type-safe API—so you can focus on your application. The library is designed to be a thin bridge, not a heavy framework.

Modular by Design We believe you should only install what you need. As a standalone package, @squoosh-kit/mozjpeg allows you to add high-quality JPEG encoding and decoding to your project without pulling in other unrelated image processing tools.

Installation

bun add @squoosh-kit/mozjpeg
# or
npm install @squoosh-kit/mozjpeg

Quick Start

import { encode, decode, createMozjpegEncoder } from '@squoosh-kit/mozjpeg';
import type { ImageInput, MozjpegEncodeOptions } from '@squoosh-kit/mozjpeg';

const imageData: ImageInput = {
  data: imageBuffer,
  width: 1920,
  height: 1080,
};

// Encode with default settings (quality 75, progressive)
const jpegBuffer = await encode(imageData);

// With custom quality
const highQuality = await encode(imageData, { quality: 90 });

// Decode a JPEG back to raw pixel data
const rawImage = await decode(jpegBuffer);

// For multiple images, create a persistent encoder
const encoder = createMozjpegEncoder('worker');
const result = await encoder(imageData, { quality: 85, progressive: true });
await encoder.terminate();

What is MozJPEG?

MozJPEG is Mozilla's improved JPEG encoder. It produces smaller JPEG files than standard libjpeg at the same visual quality, typically 10–20% smaller with no perceptible difference. It's widely used in image optimization pipelines and is a drop-in replacement for standard JPEG encoding.

Public API

Only the following exports are part of the public API and guaranteed to be stable across versions:

• encode(imageData, options?, signal?) - Encode an image to JPEG format using MozJPEG
• decode(data, signal?) - Decode a JPEG file to raw pixel data
• createMozjpegEncoder(mode?) - Create a reusable encoder function
• createMozjpegDecoder(mode?) - Create a reusable decoder function
• ImageInput type - Input image data structure
• MozjpegEncodeOptions type - MozJPEG encoding configuration
• MozjpegEncoderFactory type - Type for reusable encoder functions
• MozjpegDecoderFactory type - Type for reusable decoder functions

Real-World Examples

Upload handler with timeout

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

try {
  const jpeg = await encode(
    uploadedImage,
    {
      quality: 85,
      progressive: true, // Loads progressively in browsers
    },
    controller.signal
  );

  await saveToStorage('photo.jpg', jpeg);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Encoding timed out');
  }
} finally {
  clearTimeout(timeout);
}

Batch server-side JPEG optimization

const encoder = createMozjpegEncoder('client'); // Direct encoding, no worker

for (const imagePath of imageFiles) {
  const imageData = await loadImage(imagePath);
  const jpegData = await encoder(imageData, {
    quality: 80,
    progressive: true,
    optimize_coding: true,
  });
  await writeFile(`${imagePath}.jpg`, jpegData);
}

await encoder.terminate();

API Reference

encode(imageData, options?, signal?)

Encodes raw RGBA pixel data to JPEG format using MozJPEG.

Note: encode() uses a global singleton worker. For long-running applications where worker cleanup is important, use createMozjpegEncoder() instead.

• imageData - ImageInput object with your pixel data
• options - (optional) MozjpegEncodeOptions for quality and compression settings
• signal - (optional) AbortSignal to cancel the operation
• Returns - Promise<Uint8Array> with the encoded JPEG data

decode(data, signal?)

Decodes a JPEG file back to raw RGBA pixel data.

• data - BufferSource containing the JPEG file bytes
• signal - (optional) AbortSignal to cancel the operation
• Returns - Promise<ImageData> with decoded pixel data, width, and height

createMozjpegEncoder(mode?)

Creates a reusable encoder. More efficient for processing multiple images.

• mode - (optional) 'worker' or 'client', defaults to 'worker'
• Returns - A function with the same signature as encode()

createMozjpegDecoder(mode?)

Creates a reusable decoder.

• mode - (optional) 'worker' or 'client', defaults to 'worker'
• Returns - A function with the same signature as decode()

Cancellation Support

To cancel an encoding operation in progress, pass an AbortSignal:

const controller = new AbortController();

const encodePromise = encode(imageData, { quality: 85 }, controller.signal);
setTimeout(() => controller.abort(), 5000);

try {
  const result = await encodePromise;
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Encoding was cancelled');
  }
}

Important: If no signal is provided, the encoding operation cannot be cancelled.

Input Validation

All inputs are automatically validated before processing:

// Will throw TypeError: image must be an object
await encode(null, { quality: 85 });

// Will throw TypeError: image.data must be Uint8Array or Uint8ClampedArray
await encode({ data: [0, 0, 0, 255], width: 32, height: 32 }, { quality: 85 });

// Will throw RangeError: image.data too small
await encode(
  { data: new Uint8Array(100), width: 800, height: 600 },
  { quality: 85 }
);

Package Size

Size breakdown:

• JavaScript code: ~5-8KB gzipped
• TypeScript definitions: ~3KB
• WASM binaries: ~40-50KB gzipped

Worker Cleanup

When using worker mode, always clean up the worker when done:

const encoder = createMozjpegEncoder('worker');

try {
  const jpegData = await encoder(imageData, { quality: 85 });
} finally {
  await encoder.terminate();
}

Note: In client mode, terminate() is a no-op. It's always safe to call for consistency.

MozjpegEncodeOptions

type MozjpegEncodeOptions = {
  quality?: number; // 0–100, visual quality (default: 75)
  baseline?: boolean; // Use baseline instead of progressive JPEG (default: false)
  arithmetic?: boolean; // Use arithmetic coding (default: false)
  progressive?: boolean; // Enable progressive encoding (default: true)
  optimize_coding?: boolean; // Optimize Huffman coding tables (default: true)
  smoothing?: number; // 0–100, pre-encode smoothing (default: 0)
  color_space?: MozJpegColorSpace; // Color space: GRAYSCALE, RGB, YCbCr (default: YCbCr)
  quant_table?: number; // Quantization table preset, 0–8 (default: 3)
  trellis_multipass?: boolean; // Multi-pass trellis quantization (default: false)
  trellis_opt_zero?: boolean; // Optimize trellis zero coefficients (default: false)
  trellis_opt_table?: boolean; // Optimize trellis quantization table (default: false)
  trellis_loops?: number; // Trellis quantization passes, 1–50 (default: 1)
  auto_subsample?: boolean; // Auto chroma subsampling (default: true)
  chroma_subsample?: number; // Chroma subsampling level (default: 2)
  separate_chroma_quality?: boolean; // Enable separate chroma quality (default: false)
  chroma_quality?: number; // 0–100, chroma quality when separate (default: 75)
};

Key options:

• quality — Primary quality control. 75–85 is a good range for most photos.
• progressive — Progressive JPEGs load gradually in browsers (low-res → high-res). Usually a good default.
• optimize_coding — Slightly improves compression with no quality tradeoff. Leave enabled.
• trellis_multipass — More aggressive optimization pass; produces smaller files at the cost of encoding time.

Performance Tips

• Quality 75–85 is the sweet spot — Near-indistinguishable from higher quality at significantly smaller file size
• Use progressive for web — Better user experience; browsers can show a rough preview immediately
• Use client mode for batch jobs — Avoids worker overhead in Node/Bun scripts
• MozJPEG vs WebP vs AVIF — MozJPEG is best for maximum JPEG compatibility; for modern browsers, WebP or AVIF will be smaller

Encoding Quality & File Size

MozJPEG produces consistently smaller files than standard JPEG encoders at the same quality setting:

• Quality 80–100 — High fidelity, minimal artifacts
• Quality 60–80 — Good quality for most photos, significant size savings
• Quality 40–60 — Visible compression artifacts; useful only for thumbnails or previews
• Quality 0–40 — Heavy compression; noticeable degradation

At quality 80, MozJPEG files are typically 10–20% smaller than libjpeg output at the same setting.

Works With

• Bun - First-class support, fastest performance
• Node.js - Works great in server environments
• Browsers - Full Web Worker support for responsive UIs
• TypeScript - Complete type definitions included

License

MIT - use it freely in your projects