Deploying WebAssembly Applications

20 min read

Getting a Rust-compiled .wasm module from your machine onto a production CDN: wiring it into Vite or webpack, serving the binary with the right MIME type, and caching it correctly at the edge.

Quick Overview

A compiled WebAssembly (WASM) module is just another static asset — a .wasm file with a .js loader beside it — but it has two deployment requirements an ordinary JavaScript bundle does not: the server must send the Content-Type: application/wasm header so the browser can use the fast streaming compiler, and the binary is large enough that compression and long-lived caching genuinely matter. This file covers the last mile: integrating the wasm-pack output with a bundler (Vite/webpack), configuring static hosts and CDNs to serve .wasm correctly, and the cache/compression headers that make a Rust front end load fast. For a TypeScript/JavaScript developer, almost everything here is familiar from shipping a normal SPA — the new parts are the MIME type and the application/wasm-aware compression step.

Note: This file assumes you already have a pkg/ directory from wasm-pack. Building it (and the meaning of the web / bundler / nodejs targets) is covered in wasm-pack.md; shrinking the binary with wasm-opt/twiggy and the boundary-cost analysis live in performance.md. This file is strictly about getting the artifact served correctly in production.

TypeScript/JavaScript Example

A typical TypeScript SPA deployment is a solved problem. You build with Vite, get a hashed bundle in dist/, and ship it to a static host or CDN. The host serves .js as text/javascript, the bundler fingerprints filenames so you can cache them forever, and a netlify.toml / vercel.json / nginx config sets the headers.

1
// vite.config.ts — a normal TypeScript SPA build
2
import { defineConfig } from "vite";
3

4
export default defineConfig({
5
  build: {
6
    outDir: "dist",
7
    // Vite fingerprints assets: app.4f2a1b.js, so they can be cached forever.
8
    assetsInlineLimit: 4096,
9
  },
10
});

1
npm run build
2
# dist/assets/index-4f2a1b9c.js   <- content-hashed, immutable
3
# dist/assets/index-9e8d7c6b.css

1
# netlify.toml — cache the fingerprinted bundle aggressively
2
[[headers]]
3
  for = "/assets/*"
4
  [headers.values]
5
    Cache-Control = "public, max-age=31536000, immutable"

The mental model to carry forward: build → fingerprinted static assets → CDN with correct Content-Type and Cache-Control. Deploying a Rust WASM module reuses this exact pipeline. The only genuinely new requirements are that one of those assets is a .wasm binary that needs the application/wasm MIME type, and that it is large enough that gzip/brotli compression stops being optional.

Rust Equivalent

The Rust artifact you deploy is the pkg/ directory that wasm-pack produces. Building a small image-filter crate (crate-type = ["cdylib", "rlib"], depending only on wasm-bindgen) with the browser target produces exactly this:

1
wasm-pack build --target web

1
[INFO]:  Checking for the Wasm target...
2
[INFO]:  Compiling to Wasm...
3
[INFO]: found wasm-opt at "/opt/homebrew/bin/wasm-opt"
4
[INFO]: Optimizing wasm binaries with `wasm-opt`...
5
[INFO]:   Done in 1.15s
6
[INFO]:   Your wasm pkg is ready to publish at .../image-filter/pkg.

1
pkg/
2
├── image_filter_bg.wasm        16631 bytes  <- the binary you must serve as application/wasm
3
├── image_filter_bg.wasm.d.ts
4
├── image_filter.js              5815 bytes  <- ES-module loader (the "glue")
5
├── image_filter.d.ts
6
└── package.json

The generated package.json declares this as a real ES module package, which is what lets a bundler import it like any npm dependency:

1
{
2
  "name": "image-filter",
3
  "type": "module",
4
  "version": "0.1.0",
5
  "files": ["image_filter_bg.wasm", "image_filter.js", "image_filter.d.ts"],
6
  "main": "image_filter.js",
7
  "types": "image_filter.d.ts",
8
  "sideEffects": ["./snippets/*"]
9
}

There are two deployment paths, and which one you take depends on the wasm-pack --target you chose (see wasm-pack.md):

Path A — `--target bundler`: let Vite/webpack handle it

This is the default target and the path most production SPAs take. The pkg/ becomes a local dependency of your front-end app, and the bundler fingerprints, compresses, and copies the .wasm into dist/ for you — exactly as it already does for .js and .css.

1
# Build the WASM package for a bundler
2
wasm-pack build --target bundler
3

4
# In your Vite/webpack app, depend on it as a local package
5
npm install ../image-filter/pkg

Vite (v5+) needs no plugin for the bundler target: it understands the import of a .wasm file emitted by the glue, fingerprints it, and serves it with the correct MIME during vite dev and in the production build.

1
// src/main.ts — import the Rust functions like any ES module
2
import init, { invert, version } from "image-filter";
3

4
await init();              // load + instantiate the .wasm (async)
5
console.log(version());    // "image-filter 0.1.0"
6

7
const pixels = new Uint8Array([10, 20, 30, 255]);
8
invert(pixels);            // pixels is now [245, 235, 225, 255]

Tip: On older webpack 4 you needed experiments.asyncWebAssembly. With webpack 5 and Vite 5+ the WASM import works out of the box for the bundler target. If your bundler predates that, prefer the web target (Path B) and skip the bundler integration entirely.

Path B — `--target web`: ship `pkg/` as static files

With --target web, the glue is a self-contained ES module that loads the binary itself — no bundler required. You copy pkg/ into your static site and <script type="module"> it. The catch is that the glue uses WebAssembly.instantiateStreaming, and streaming only works if your server sends Content-Type: application/wasm. This is the single most common WASM deployment failure, and it is the focus of the next section.

1
<!-- index.html, deployed as a static file alongside pkg/ -->
2
<script type="module">
3
  import init, { version } from "./pkg/image_filter.js";
4
  await init();                 // fetches ./pkg/image_filter_bg.wasm
5
  document.body.textContent = version();
6
</script>

Detailed Explanation

Why `application/wasm` is mandatory, not cosmetic

Look at what the generated loader actually does. The web-target glue resolves the binary’s URL relative to itself and fetches it:

1
// generated image_filter.js (excerpt) — how the binary is located
2
if (module_or_path === undefined) {
3
    module_or_path = new URL('image_filter_bg.wasm', import.meta.url);
4
}
5
// ...
6
module_or_path = fetch(module_or_path);

Then it tries the fast path — WebAssembly.instantiateStreaming, which compiles the module while it is still downloading — and contains an explicit fallback with a warning if your server got the MIME type wrong:

1
// generated image_filter.js (excerpt) — the streaming path + real warning
2
if (typeof WebAssembly.instantiateStreaming === 'function') {
3
    try {
4
        return await WebAssembly.instantiateStreaming(module, imports);
5
    } catch (e) {
6
        const validResponse = module.ok && expectedResponseType(module.type);
7
        if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
8
            console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
9
        } else { throw e; }
10
    }
11
}
12
const bytes = await module.arrayBuffer();
13
return await WebAssembly.instantiate(bytes, imports);

That warning string is emitted verbatim by wasm-bindgen’s glue (it is not something this guide wrote). If you see it in production, your host is serving the .wasm as application/octet-stream or text/plain. The page still works — the glue falls back to arrayBuffer() + WebAssembly.instantiate — but you lose streaming compilation, so the module is downloaded fully before compilation begins instead of overlapping the two. For a multi-megabyte Rust front end that is a measurable startup regression.

Most servers already know `.wasm` — but not all

The good news: the .wasm → application/wasm mapping has been in the IANA registry for years, so modern tooling ships it by default. For example, Python 3’s standard-library http.server (the one used for local testing in first-wasm.md) already maps it:

1
$ python3 -c "import mimetypes; print(mimetypes.guess_type('x.wasm'))"
2
('application/wasm', None)

Vite, Netlify, Vercel, Cloudflare Pages, and GitHub Pages all serve .wasm correctly out of the box. The servers that historically did not include older nginx releases (the bundled mime.types lacked the wasm entry until recent versions) and any hand-rolled Node http server, because Node has no built-in static MIME database — express/serve-static get it from the mime-types package, and a raw createServer sets nothing unless you do.

Compression: the part that actually moves the needle

A .wasm binary is highly compressible. The image-filter module above is 16,631 bytes raw (built with wasm-pack 0.13.1 / wasm-bindgen 0.2.122 / wasm-opt v129 — exact bytes vary by toolchain version), but transfers far smaller once the server compresses it:

Encoding	Bytes on the wire	vs raw
none (raw `.wasm`)	16,631	100%
`gzip -9`	7,728	46%
`brotli -q 11`	6,687	40%

For real Rust front ends (hundreds of KB to a few MB), brotli routinely cuts transfer size by 60–70%. Every serious CDN compresses application/wasm automatically if you let it — the failure mode is a host whose compression allowlist is keyed on Content-Type and does not include application/wasm. That is one more reason the MIME type must be right: it gates compression too.

Note: Shrinking the uncompressed binary itself — wasm-opt -Oz, twiggy to find bloat, trimming panic machinery — is the subject of performance.md. This section is about the transport layer: compress whatever binary you ship, and cache it.

Caching: fingerprint and freeze

The .wasm binary is immutable for a given build. With the bundler target, Vite/webpack content-hash the filename (image_filter_bg.<hash>.wasm), so you can set Cache-Control: public, max-age=31536000, immutable — identical to how you cache a hashed .js bundle. With the web target the filename is not hashed by default (image_filter_bg.wasm), so either let a bundler hash it or version the path yourself (/v3/pkg/...) before applying an immutable cache, otherwise a deploy can leave clients pinned to a stale binary.

Key Differences

Concern	TypeScript SPA asset	Rust `.wasm` asset
Artifact	`index-<hash>.js` (text)	`*_bg.wasm` (binary) + `.js` glue
Required `Content-Type`	`text/javascript` (everyone gets it right)	`application/wasm` (some hosts miss it)
Cost of wrong MIME	none	loses `instantiateStreaming` → slower startup
Compression	gzip/brotli, always on	gzip/brotli, only if allowlist includes `application/wasm`
Fingerprinting	automatic in every bundler	automatic with `--target bundler`; manual with `--target web`
Instantiation	synchronous module eval	async `await init()` before first call
Cross-origin isolation	not needed	needed only if you use WASM threads (`SharedArrayBuffer`)

The deepest conceptual difference is the async load. A JavaScript module is ready the instant its <script> evaluates; a WASM module must be fetched, compiled, and instantiated, all asynchronous. Your deployment must therefore tolerate a brief window where the Rust functions are not yet callable — show a loading state, and never call an export before await init() resolves.

Common Pitfalls

Pitfall 1: Server serves `.wasm` as `application/octet-stream`

The symptom is the exact wasm-bindgen console warning shown above and a measurably slower first load. The fix is host-specific configuration. nginx:

1
types {
2
    application/wasm wasm;
3
}
4

5
location ~ \.wasm$ {
6
    add_header Content-Type application/wasm;
7
    add_header Cache-Control "public, max-age=31536000, immutable";
8
    gzip on;
9
    gzip_types application/wasm;   # gzip won't touch it unless listed
10
}

Netlify (netlify.toml) and Vercel (vercel.json) set it via headers config:

1
[[headers]]
2
  for = "/*.wasm"
3
  [headers.values]
4
    Content-Type = "application/wasm"
5
    Cache-Control = "public, max-age=31536000, immutable"

Pitfall 2: A hand-rolled Node server sets no MIME at all

A raw node:http server returns no Content-Type for a .wasm file unless you set it. The minimal correct handler:

1
// server.mjs — a static server that serves .wasm correctly
2
import { createServer } from "node:http";
3
import { readFile } from "node:fs/promises";
4

5
createServer(async (req, res) => {
6
  if (req.url.endsWith(".wasm")) {
7
    const buf = await readFile(`.${req.url}`);
8
    res.setHeader("Content-Type", "application/wasm");        // the critical line
9
    res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
10
    res.end(buf);
11
  } else {
12
    res.statusCode = 404;
13
    res.end("not found");
14
  }
15
}).listen(8099);

Verified with curl, this returns the right header:

1
$ curl -sI http://localhost:8099/image_filter_bg.wasm | grep -i content-type
2
Content-Type: application/wasm

Pitfall 3: `strip = true` in `[profile.release]` breaks the `wasm-pack` build

A natural size-optimization profile is tempting, but adding strip = true while wasm-opt is installed makes wasm-pack fail. This profile:

1
# Cargo.toml — DON'T add strip here when wasm-opt runs
2
[profile.release]
3
opt-level = "z"
4
lto = true
5
codegen-units = 1
6
panic = "abort"
7
strip = true          # <- this line causes the failure below

produces this real error (wasm-pack 0.13.1 driving wasm-opt v129 — the exact validator text is version-sensitive). The compile succeeds; the failure is in the post-build wasm-opt pass, and the diagnostic that matters is the wasm-validator block at the top, not the generic tail:

1
[wasm-validator error in function 2] unexpected false: memory.copy operations require bulk memory operations [--enable-bulk-memory-opt], on
2
(memory.copy
3
 (local.get $4)
4
 (local.get $0)
5
 (local.get $1)
6
)
7
[wasm-validator error in function 33] unexpected false: memory.fill operations require bulk memory [--enable-bulk-memory-opt], on
8
(memory.fill
9
 (local.get $1)
10
 (i32.const 0)
11
 (local.get $0)
12
)
13
Fatal: error validating input
14
Error: failed to execute `wasm-opt`: exited with exit status: 1
15
  full command: ".../wasm-opt" ".../image_filter_bg.wasm" "-o" ".../image_filter_bg.wasm-opt.wasm" "-O"
16
To disable `wasm-opt`, add `wasm-opt = false` to your package metadata in your `Cargo.toml`.

The cause is not double-stripping. With strip = true, the binary wasm-pack hands to its post-build wasm-opt pass fails wasm-opt’s validator: the binary uses bulk-memory operations (memory.copy/memory.fill), but those are not enabled for that validation run, so wasm-opt aborts before it can optimize anything. The fix is to drop strip = true and let wasm-opt own the size pass; the rest of the profile is fine and builds cleanly. (Symbol stripping and size tuning belong in performance.md.)

Pitfall 4: Calling an export before `init()` resolves

1
import init, { version } from "./pkg/image_filter.js";
2
console.log(version());   // throws: wasm is undefined — init() hasn't run
3
await init();
4
console.log(version());   // now the module is instantiated

Because instantiation is asynchronous, any code that touches an export must run after await init() (or inside a .then). This bites people who treat the WASM module like a synchronously-loaded JS module.

Pitfall 5: Forgetting cross-origin isolation when using WASM threads

If your Rust uses wasm-bindgen-rayon or any threaded build, the browser only exposes SharedArrayBuffer when the page is cross-origin isolated, which requires two response headers on the HTML document:

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

Without them the module instantiates but thread spawning fails at runtime. Single-threaded WASM (the common case) does not need these headers — adding them unnecessarily can break third-party embeds, so only set them when you actually ship threads.

Best Practices

Prefer --target bundler for an app, --target web for a static drop-in. Inside a Vite/webpack SPA, let the bundler fingerprint, compress, and MIME-tag the .wasm for you. Use web only when there is no build step.
Verify the MIME type after every deploy. A one-line curl -sI https://your.site/path/to_bg.wasm | grep -i content-type catches the most common production WASM bug in seconds.
Compress application/wasm at the edge. Confirm your CDN’s compression allowlist includes the WASM MIME type; brotli typically cuts a Rust binary by 60–70% on the wire.
Fingerprint, then cache immutably. Hashed filename + Cache-Control: public, max-age=31536000, immutable. With the web target, add the hash yourself or version the directory so a redeploy doesn’t strand clients on a stale binary.
Keep wasm-opt enabled and don’t fight it. Let wasm-pack run wasm-opt; do not also set Cargo strip = true (Pitfall 3). Tune size in the build, not by stripping twice.
Only enable COOP/COEP when you ship threads. Cross-origin isolation is a requirement for SharedArrayBuffer, not for ordinary single-threaded modules.
Show a loading state. Render a placeholder until await init() resolves so the async instantiation window is invisible to users.

Real-World Example

A production-flavored setup: a Rust image-filter module deployed inside a Vite SPA, served behind nginx with correct MIME, compression, and caching. This is the full, build-verified picture from Rust source to served headers.

The Rust crate (crate-type = ["cdylib", "rlib"], wasm-bindgen = "0.2"), built with wasm-pack build --target bundler:

1
// src/lib.rs — compile-verified against wasm32-unknown-unknown
2
use wasm_bindgen::prelude::*;
3

4
/// Invert the colors of an RGBA pixel buffer in place.
5
/// `pixels` is a flat array of bytes: [r, g, b, a, r, g, b, a, ...].
6
#[wasm_bindgen]
7
pub fn invert(pixels: &mut [u8]) {
8
    for chunk in pixels.chunks_exact_mut(4) {
9
        chunk[0] = 255 - chunk[0]; // R
10
        chunk[1] = 255 - chunk[1]; // G
11
        chunk[2] = 255 - chunk[2]; // B
12
        // chunk[3] is alpha, left unchanged
13
    }
14
}
15

16
#[wasm_bindgen]
17
pub fn version() -> String {
18
    "image-filter 0.1.0".to_string()
19
}

The size-optimized release profile (note: no strip — see Pitfall 3):

1
[package]
2
name = "image-filter"
3
version = "0.1.0"
4
edition = "2024"
5

6
[lib]
7
crate-type = ["cdylib", "rlib"]
8

9
[dependencies]
10
wasm-bindgen = "0.2"
11

12
[profile.release]
13
opt-level = "z"     # optimize for size
14
lto = true          # link-time optimization
15
codegen-units = 1   # better optimization at the cost of build time
16
panic = "abort"     # drop unwinding machinery

Wiring it into the SPA and gating UI on init():

1
import init, { invert, version } from "image-filter";
2

3
async function main() {
4
  const status = document.getElementById("status")!;
5
  status.textContent = "Loading WASM…";
6
  await init();                               // async instantiation window
7
  status.textContent = `Ready: ${version()}`;
8

9
  // Apply the Rust filter to a canvas frame:
10
  const canvas = document.querySelector("canvas")!;
11
  const ctx = canvas.getContext("2d")!;
12
  const frame = ctx.getImageData(0, 0, canvas.width, canvas.height);
13
  invert(frame.data);                         // mutates the RGBA buffer in Rust
14
  ctx.putImageData(frame, 0, 0);
15
}
16

17
main();

1
# CI build + verify the deployed MIME type
2
wasm-pack build --target bundler
3
npm --prefix web ci
4
npm --prefix web run build           # Vite fingerprints image_filter_bg.<hash>.wasm
5
# after deploy, smoke-test the header:
6
curl -sI https://app.example.com/assets/image_filter_bg.4f2a1b.wasm | grep -i 'content-type\|content-encoding'
7
# Content-Type: application/wasm
8
# Content-Encoding: br

The nginx config in front of the static dist/:

1
# nginx.conf — serve a fingerprinted Vite + WASM build
2
server {
3
    listen 443 ssl;
4
    root /var/www/app/dist;
5

6
    types { application/wasm wasm; }   # ensure the MIME type exists
7

8
    # brotli/gzip the WASM (compression module must list the MIME type)
9
    gzip on;
10
    gzip_types application/wasm application/javascript text/css;
11

12
    # Fingerprinted assets are immutable -> cache for a year
13
    location /assets/ {
14
        add_header Cache-Control "public, max-age=31536000, immutable";
15
        try_files $uri =404;
16
    }
17

18
    # SPA fallback for client-side routing
19
    location / {
20
        try_files $uri /index.html;
21
    }
22
}

The verified deployment facts behind this setup, all measured on the real artifact:

wasm-pack build --target web of the crate above emits a 16,631-byte image_filter_bg.wasm (wasm-pack 0.13.1 / wasm-bindgen 0.2.122 / wasm-opt v129; exact bytes vary by toolchain version).
That binary compresses to 7,728 bytes with gzip -9 and 6,687 bytes with brotli -q 11 — so the brotli transfer is ~40% of raw.
A static server that sets Content-Type: application/wasm lets the browser use streaming instantiation; one that does not triggers the wasm-bindgen fallback warning quoted earlier.

Exercises

Exercise 1: Catch a wrong MIME type

Difficulty: Beginner

Objective: Reproduce and then fix the application/wasm deployment bug.

Instructions:

Build any wasm-pack --target web package and serve the pkg/ directory with a static server that returns Content-Type: application/octet-stream for .wasm (a misconfigured one).
Open the page, find the wasm-bindgen warning in the browser console, and write it down.
Switch to a server that sends application/wasm and confirm the warning disappears.

Solution

The misconfigured server triggers exactly this wasm-bindgen-emitted console warning (it is part of the generated glue, not your code):

1
`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:

A correct static server sets the header explicitly. A minimal Node version:

1
import { createServer } from "node:http";
2
import { readFile } from "node:fs/promises";
3

4
createServer(async (req, res) => {
5
  if (req.url.endsWith(".wasm")) {
6
    res.setHeader("Content-Type", "application/wasm");
7
    res.end(await readFile(`.${req.url}`));
8
  } else {
9
    res.statusCode = 404;
10
    res.end("not found");
11
  }
12
}).listen(8099);

Verifying the header confirms the fix:

1
$ curl -sI http://localhost:8099/pkg/your_module_bg.wasm | grep -i content-type
2
Content-Type: application/wasm

With the correct MIME type, WebAssembly.instantiateStreaming succeeds and the warning is gone. (Python’s python3 -m http.server also serves it correctly, since its standard library already maps .wasm → application/wasm.)

Exercise 2: Measure compression savings

Difficulty: Intermediate

Objective: Quantify why compressing application/wasm matters before configuring a CDN.

Instructions:

Build a wasm-pack package and locate its _bg.wasm file.
Measure the raw size, the gzip -9 size, and (if brotli is installed) the brotli -q 11 size.
Compute each compressed size as a percentage of raw, and decide which Content-Encoding you would prefer at the edge.

Solution

1
RAW=$(wc -c < pkg/your_module_bg.wasm)
2
GZ=$(gzip -9 -c pkg/your_module_bg.wasm | wc -c)
3
BR=$(brotli -q 11 -c pkg/your_module_bg.wasm | wc -c)
4
echo "raw=$RAW gzip=$GZ brotli=$BR"

For the 16,631-byte image-filter module from this chapter (wasm-pack 0.13.1 / wasm-bindgen 0.2.122 / wasm-opt v129 — your exact bytes will vary with toolchain version), the real numbers are:

1
raw=16631 gzip=7728 brotli=6687

That is 46% of raw for gzip and 40% for brotli. Brotli wins, so configure the CDN to prefer Content-Encoding: br (with gzip as the fallback for clients that do not advertise br in Accept-Encoding). The key configuration step is ensuring the compression allowlist includes application/wasm — many defaults compress text/* and application/javascript but silently skip the WASM MIME type.

Exercise 3: Write a cache-and-MIME header policy

Difficulty: Advanced

Objective: Produce a correct production header policy for a fingerprinted WASM build and reason about the web-vs-bundler caching difference.

Instructions:

Write a netlify.toml (or equivalent) that serves every .wasm as application/wasm and caches /assets/* immutably for one year.
Explain in one or two sentences why this immutable cache policy is safe for a --target bundler build but dangerous for a --target web build deployed at a fixed path.

Solution

1
[[headers]]
2
  for = "/*.wasm"
3
  [headers.values]
4
    Content-Type = "application/wasm"
5

6
[[headers]]
7
  for = "/assets/*"
8
  [headers.values]
9
    Cache-Control = "public, max-age=31536000, immutable"

The immutable policy is safe for --target bundler because Vite/webpack content-hash the filename (image_filter_bg.<hash>.wasm): a new build produces a new URL, so caching the old one forever can never serve stale code. It is dangerous for a --target web build served at a fixed path like /pkg/image_filter_bg.wasm, because the filename never changes — an immutable, max-age=31536000 cache can pin clients to last month’s binary across deploys. For the web target you must either let a bundler hash the file, version the directory (/v3/pkg/...), or use a short max-age with revalidation instead of immutable.

Deploying WebAssembly Applications

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Path A — --target bundler: let Vite/webpack handle it

Path B — --target web: ship pkg/ as static files

Detailed Explanation

Why application/wasm is mandatory, not cosmetic

Most servers already know .wasm — but not all

Compression: the part that actually moves the needle

Caching: fingerprint and freeze

Key Differences

Common Pitfalls

Pitfall 1: Server serves .wasm as application/octet-stream

Pitfall 2: A hand-rolled Node server sets no MIME at all

Pitfall 3: strip = true in [profile.release] breaks the wasm-pack build

Pitfall 4: Calling an export before init() resolves

Pitfall 5: Forgetting cross-origin isolation when using WASM threads

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Catch a wrong MIME type

Exercise 2: Measure compression savings

Exercise 3: Write a cache-and-MIME header policy

Path A — `--target bundler`: let Vite/webpack handle it

Path B — `--target web`: ship `pkg/` as static files

Why `application/wasm` is mandatory, not cosmetic

Most servers already know `.wasm` — but not all

Pitfall 1: Server serves `.wasm` as `application/octet-stream`

Pitfall 3: `strip = true` in `[profile.release]` breaks the `wasm-pack` build

Pitfall 4: Calling an export before `init()` resolves