rollup-plugin-wasm-brotli

This Rollup plugin uses brotli-unicode (which in turn uses Brotli) to compress an inline a WASM file (.wasm), directly into your JavaScript bundle.

Overview

The inline-wasm plugin:

• Automatically detects new URL('path.wasm', import.meta.url) calls in your code.
• Resolves .wasm file paths (including from node modules).
• Reads the .wasm file, compresses it using brotli-unicode.
• Inlines the compressed data into your bundle.
• At runtime, decompresses and instantiates the WebAssembly module.

This reduces HTTP requests and improves load performance, especially when bundling for the web. But it comes at a cost: The decopression itself is a WASM artifact. This increases the memory requirements and load time on the client.

Status

This plugin is highly experimental! Use it at your own risk, there might be bugs.

Prerequisites

Make sure you have the following installed:

• Rollup
• This plugin

npm install --save-dev rollup rollup-plugin-wasm-brotli

Note: brotli-unicode is used for compression and decompression. It supports both Node.js and browser environments.

Installation & Setup

1. Create or Update Your rollup.config.js

import inlineWasm from "rollup-plugin-inline-wasm";

export default {
  input: "src/main.js",
  output: {
    dir: "dist",
    format: "esm"
  },
  plugins: [await inlineWasm()]
};

Simple example

File structure

project-root/
├── src/
│   ├── main.js
│   └── math.wasm
├── rollup.config.js
└── package.json

Example: src/main.js

// This will be transformed by the plugin
const wasmUrl = new URL("./math.wasm", import.meta.url);

const wasmModule = await WebAssembly.instantiateStreaming(fetch(wasmUrl));

After processing, Rollup will:

• Inline the math.wasm file.
• Replace the new URL(...) with a blob URL created from decompressed bytes.
• Inject necessary imports and functions.

Practical Example

This example is a bit more pactical. Make sure to include @projektemacher/rollup-plugin-wasm-brotli before resolving other imports. Also it's important to await the results of the plugins, since the compression is async.

// rollup.config.ts
import { defineConfig } from "rollup";
import typescript from "@rollup/plugin-typescript";
import nodeResolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import { inlineWasm } from "@projektemacher/rollup-plugin-wasm-brotli";

export default defineConfig({
  input: "src/index.ts",
  output: {
    file: "dist/bundle.js",
    format: "esm"
  },
  plugins: [
    nodeResolve({
      extensions: [".js", ".ts", ".wasm"] // ← .wasm explizit erlauben
    }),
    await inlineWasm(),
    commonjs(),
    typescript()
  ]
});

Advanced configuration and usage

The plugin does not accept options currently, but you can customize behavior by modifying the source or extending it.

Bundling with Esbuild

By default esbuild converts the charset to be ASCII, this leads to ecaped unicode squences which in turn take more byte per unicode character. You can instruct esbuild to create a unicode output like this:

esbuild --bundle --charset=utf8 /path/to/file.js

WASM generated by wasm-pack (Rust)

Usually you need to make sure that the WASM file itself if your wrapper code was generated by wasm-pack, like this:

import init, { Hdt } from 'hdt/hdt.js';
import wasm_hdt from 'hdt/hdt_bg.wasm';

const wasmReady: Promise<void> = (async () => {
  await init({ wasm_hdt });
})();

Make sure this weird construct is present, otherwise the plugin won't find your WASM file.

How It Works (Under the Hood)

1. resolveId: Resolves .wasm file paths (relative, absolute, or from node modules).
2. load: Reads the .wasm file, compresses it with brotli-unicode, and generates a module that exports getWasmBytes() and loadWasm().
3. transform: Replaces new URL('file.wasm', import.meta.url) with a dynamic blob URL using the inlined compressed data.

Comparision

This comparision is based on the implementation for this blog post, which includes OxiGraph and HDT Rust module

Without plugin

| Größe (Bytes) | Datei | | ------------- | -------------------------------------- | | 1,191,284 | wikidata-hdt/dist/client-sparql.js | | 2,609,124 | wikidata-hdt/dist/client-sparql.js.map | | 714 | wikidata-hdt/dist/client-sparql.scss | | 181,638 | wikidata-hdt/dist/hdt_bg.wasm | | 3,954,968 | wikidata-hdt/dist/web_bg.wasm |

Without the plugin the files wikidata-hdt/dist/client-sparql.js and both WASM files are needed. 5,327,890 Bytes in total.

With plugin

| Größe (Bytes) | Datei | | ------------- | -------------------------------------- | | 3,060,899 | wikidata-hdt/dist/client-sparql.js | | 4,493,750 | wikidata-hdt/dist/client-sparql.js.map | | 714 | wikidata-hdt/dist/client-sparql.scss | | 181,638 | wikidata-hdt/dist/hdt_bg.wasm | | 3,954,968 | wikidata-hdt/dist/web_bg.wasm |

With the plugin only wikidata-hdt/dist/client-sparql.js is needed. 3,060,899 in total. About 57.4% of the original size.