WASM を同梱した npm ライブラリで、.wasm ファイルはどこを通ってブラウザに届くか

JS だけのライブラリなら「npm に置けば、利用者のバンドラーが混ぜてくれる」で済む。 WASM を同梱すると `.wasm` というバイナリファイルが関わるため、関わる場所が 5 つに分かれ、それぞれで壊れ方が違う。

ライブラリ名・ファイル名の my-lib / x.wasm は抽象的な代表例。カードが置かれたセルがそのファイルの初登場。

配布フロー図

作者npm利用者来訪者build 前 (ソース)build 後 (生成物)npm publishpnpm addbundle + deployfetch + compilewasm/src/lib.rsTXT#[wasm_bindgen]pub fn step(ptr: usize, n: usize, dt: f32) {計算ロジックの正本。配布管を流れる情報の源src/loader.tsTXTconst res = await fetch( new URL('./x.wasm', import.meta.url)).wasm の位置解決 + 初期化手順。配布後も wasm.js として残るlib/esm/wasm.jsテキストのままコピーtgz 内 wasm.jsnode_modules/…/wasm.jsminify 後 (index js へ混ぜ込み)const e=await fetch("/assets/ x-9c2e.wasm"),t=await WebAssembly.instantiateStreaming(e)src/index.tsTXTexport function createEngine( opts: Options): Engine { … }JS 版実装と公開 API の形。フォールバック兼lib/esm/index.jstgz 内 index.jsnode_modules/…/index.jsminify 後 (index js へ混ぜ込み)function createEngine(e){ return new Engine(e)}—まだ無いlib/esm/x.wasmBIN00 61 73 6d 01 00 00 001a 85 80 80 00 …機械語 (バイトコード)。人は読めないが実行に必要な全情報tgz 内エントリ同一バイト列node_modules/x.wasm展開コピーx-9c2e.wasmhash リネーム・中身同一線形メモリへ展開0000 00 00 80 3f 00 00 00 40 …package.jsonTXT"files": ["lib"],"exports": { "./wasm": "…/wasm.js" }配布ルール。何を同梱しどの入口を公開するかmy-lib-x.y.z.tgzBIN1f 8b 08 00 …(gzip ヘッダ)「バージョン x.y.z =この中身」の対応付けtar 展開 →node_modules/ へbuild (cargo + wasm-opt)new URL('./x.wasm') で位置参照files: ["lib"] で同梱tar 展開 (pnpm add)URL 書き換えfetch + instantiateStreaming情報構造人が読むテキストが正本壊れやすい所ツールチェーンの用意(CI も同じ版)情報構造バイナリは派生物(git 管理外・再生成可能)情報構造immutable スナップショット。再コンパイルされない情報構造まだ実行されない。バンドラーの解析対象壊れやすい所new URL を解決できるか(CJS では import.meta.url 不可)情報構造静的ファイル群。JS と wasm は別リクエスト (+1)壊れやすい所Content-Type: wasm 必須。CSP は 'wasm-unsafe-eval'情報構造ここで初めて実行状態。初期化は非同期壊れやすい所失敗 (CSP/404/MIME/未対応)は JS 版で吸収

JS だけのライブラリとの違い

項目

JS だけ

WASM を同梱

パッケージの中身

lib/esm / lib/cjs / 型定義

+ .wasm バイナリ

読み込み

import した時点で使える

取得 + コンパイルが非同期

API

同期で返せる

await が要る。または JS 版で先に動かし、後から差し替える

ファイル位置の解決

不要

new URL('./x.wasm', import.meta.url)。CJS では import.meta.url が使えない

base64 で JS に埋め込む

—

位置の問題は消えるがサイズ約 1.33 倍。非同期は残る

CDN から 1 行

そのまま動く

同じ場所から配信されるので動く。リクエストは 1 回増える

CSP

制約なし

'wasm-unsafe-eval' が要る

ビルドと CI

tsc だけ

Rust 等のツールチェーンが増える

デバッグ

DevTools でそのまま

追いにくい。テストは JS 版と結果が一致するかの比較が中心

参考: MDN WebAssembly