Skip to content

Deploying the Browser WASM

The browser integration ships a single ~40 MB WebAssembly module as part of @oicana/browser. It is fetched once and lives in the browser cache afterwards, so the goal in production is to make that first fetch fast and let the runtime use it efficiently. This guide covers what to set up beyond the getting-started chapter.

The WASM file compresses very well. It comes in at about 40 MB uncompressed, ~17 MB gzip, ~12 MB brotli. But several popular CDNs cap on-the-fly compression at around 10 MB and silently serve the uncompressed file when an asset crosses that limit.

The fix is to pre-compress at build time and serve the .wasm.br (and .wasm.gz) file directly. Most static-asset hosts pick up compressed siblings automatically when they exist, and almost all bundlers can produce them in one step:

  • Vite: add vite-plugin-compression2 and list both algorithms.
  • Webpack / Next.js: compression-webpack-plugin with two instances (one per algorithm).
  • Self-hosted nginx: brotli_static on; gzip_static on; and ship .wasm.br / .wasm.gz next to .wasm in your build output.

Compression plugins ship a default file filter built for text assets, and .wasm is not in it. E.g. for vite:

vite.config.ts
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
import { compression } from 'vite-plugin-compression2';
export default defineConfig({
plugins: [
react(),
compression({
include: /\.(js|mjs|json|css|html|wasm)$/i,
algorithms: ['gzip', 'brotliCompress'],
}),
],
});

Brotli at its default quality is slow on a file this size: expect the production build to take over a minute longer.

Without an argument, initialize() loads the module that ships in the package through the standard new URL(..., import.meta.url) form:

await initialize();

Vite 8, webpack 5, Next.js (Turbopack and webpack), Parcel, and Rspack resolve that form, emit the WASM as a content-hashed asset, and rewrite the URL to point at it. It also works without a bundler, for example with an import map or from a CDN like jsDelivr, unpkg, or esm.sh.

Some tools need extra setup:

  • Vite 7 and older: production builds work, but the dev server pre-bundles dependencies and serves index.html instead of the WASM. Add @oicana/browser to optimizeDeps.exclude in vite.config.ts.
  • Rollup: add @web/rollup-plugin-import-meta-assets.
  • esbuild, Bun, and Angular: they leave the URL as it is, so the request fails with a 404. Copy node_modules/@oicana/browser/wasm/oicana_browser_wasm_bg.wasm next to your bundle under its original name as part of the build, for example with an assets entry in angular.json. initialize() still needs no argument.

To serve the file from somewhere else, pass its URL to initialize(), for example await initialize('/oicana_browser_wasm_bg.wasm').

The browser will use the streaming WebAssembly.instantiateStreaming path only when the response is served as application/wasm. Some hosts default to application/octet-stream, which forces a slower fallback that downloads the full module before instantiation can start.

Static-asset hosts usually map the extension correctly. If you’re behind a custom server or proxy, double-check the response headers in the browser’s network tab:

Content-Type: application/wasm
Content-Encoding: br # if you're pre-compressing
Cache-Control: public, max-age=31536000, immutable

The immutable cache hint is safe when your bundler emits the WASM as a content-hashed asset (the bundlers that resolve new URL(..., import.meta.url) do this) so that the URL changes every time the file changes. The package itself ships the file under a fixed name, so if you copy it or serve it directly from node_modules, skip immutable or you risk pinning a stale module for up to a year.

Even with brotli and a fast CDN, the first visit will spend a couple of seconds downloading and instantiating the module on slower connections. Render a skeleton or “preparing PDF engine…” placeholder until your await initialize() resolves; subsequent visits are typically instant because the browser cache absorbs the cost.

A common pattern is to call initialize() early at app boot rather than on the first user interaction so the module is warmed up by the time someone clicks the button that triggers compilation.

PDF compilation is CPU-bound and runs synchronously inside the WASM module. On the main thread that means the UI freezes for the duration of template.export(...). That can be OK for a quick test, but is painful for a real app.

The fix is the standard one: instantiate @oicana/browser inside a Web Worker and post messages from the UI thread to request compilations. The worker keeps the same Template instance alive across calls, so the WASM module is initialized once and the per-request cost is just the message round-trip plus the actual compile.