wasm-vips

libvips for the browser and Node.js, compiled to WebAssembly with Emscripten.

Programs that use wasm-vips don't manipulate images directly, instead they create pipelines of image processing operations building on a source image. When the end of the pipe is connected to a destination, the whole pipeline executes at once, streaming the image in parallel from source to destination a section at a time. Because wasm-vips is parallel, it's quick, and because it doesn't need to keep entire images in memory, it's light.

An engine that supports WebAssembly SIMD and WebAssembly Exception Handling. This is present on most major browser engines and is part of Baseline 2023.

For V8-based engines, at least version 9.5 is required, this corresponds to Chrome 95, Node.js 17.0.0 and Deno 1.16.0.

For Spidermonkey-based engines, the JavaScript engine used in Mozilla Firefox and whose version numbers are aligned, at least version 100 is required.

For JavaScriptCore-based engines, the built-in JavaScript engine for WebKit, at least version 615.1.17 is required. This corresponds to Safari 16.4.

Chrome	Firefox	Safari	Edge	Node.js	Deno
✔️ version 95+	✔️ version 100+	✔️ version 16.4+	✔️ version 95+	✔️ version 17.0+	✔️ version 1.16+

wasm-vips can be installed with your favorite package manager.

npm install wasm-vips

yarn add wasm-vips

Requires vips.js (or vips-es6.js) and vips.wasm to be served from the same directory.

Since wasm-vips requires the SharedArrayBuffer API, the website needs to opt-in to a cross-origin isolated state, by serving the following HTTP headers on both the main document and vips*.js script:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

^{See https://web.dev/coop-coep/ for more information.}

After that, wasm-vips can be imported and initialized like this:

<script src="vips.js"></script>
<script type="module">
  const vips = await Vips();
</script>

Or, if you prefer to use ES6 modules:

<script type="module">
  import Vips from './vips-es6.js';
  const vips = await Vips();
</script>

^{This requires support for ES6 modules in workers.}

On Node.js, wasm-vips is published as a dual-package, so it can be imported as both CommonJS and ES6 module:

// ES6 module
import Vips from 'wasm-vips';

// CommonJS module
const Vips = require('wasm-vips');

Then, wasm-vips can be initialized like this:

// Usage with top-level await
const vips = await Vips();

// Usage with .then
Vips().then((vips) => {
  // Code here
});

On Deno, wasm-vips can be imported by using the npm: specifier:

import Vips from 'npm:wasm-vips';

const vips = await Vips();

// Load an image from a file
using im = vips.Image.newFromFile('owl.jpg');

// Put im at position (100, 100) in a 3000 x 3000 pixel image,
// make the other pixels in the image by mirroring im up / down /
// left / right, see
// https://www.libvips.org/API/current/method.Image.embed.html
using embed = im.embed(100, 100, 3000, 3000, {
  extend: 'mirror'
});

// Multiply the green (middle) band by 2, leave the other two alone
using multiply = embed.multiply([1, 2, 1]);

// Make an image from an array constant, convolve with it
using mask = vips.Image.newFromArray([
  [-1, -1, -1],
  [-1, 16, -1],
  [-1, -1, -1]
], 8.0);

using convolve = multiply.conv(mask, {
  precision: 'integer'
});

// Finally, write the result to a buffer
const outBuffer = convolve.writeToBuffer('.jpg');

^{If not transpiling, this requires support for the using keyword. On Node.js, you can enable it with the --js-explicit-resource-management CLI flag.}