wasm-pack & Bundling

Construa e distribua pacotes WASM consumíveis por npm com wasm-pack e bundlers de frontend.

Receita

cargo install wasm-pack
wasm-pack build --target bundler --release

pkg/
  mylib.js          # Cola JS
  mylib_bg.wasm     # Binário WASM
  mylib.d.ts        # Tipos TypeScript
  package.json      # Metadados npm

Quando usar isso: Publicar Rust WASM para npm para consumidores React, Vite ou webpack.

Exemplo de Trabalho

// package.json (projeto frontend raiz)
{
  "dependencies": {
    "mylib": "file:../mylib/pkg"
  }
}

// src/worker.ts
import init, { process_data } from "mylib";
 
export async function run(input: Uint8Array) {
  await init();
  return process_data(input);
}

# Rust crate Cargo.toml
[package]
name = "mylib"
version = "0.1.0"
edition = "2024"
 
[lib]
crate-type = ["cdylib"]
 
[dependencies]
wasm-bindgen = "0.2"

O que isso demonstra:

wasm-pack emite um pacote npm completo em pkg/
--target bundler é adequado para tree-shaking do webpack/vite
init() deve ser executado antes de chamar as funções exportadas
Links de caminho file: locais durante o desenvolvimento

Mergulho Profundo

Alvos do wasm-pack

Alvo	Consumidor
`web`	`<script type="module">` do navegador
`bundler`	webpack, vite, parcel
`nodejs`	Node.js com acesso a fs
`deno`	Importações Deno

Configuração do Vite

// vite.config.ts
export default {
  optimizeDeps: {
    exclude: ["mylib"],
  },
};

Exclua pacotes WASM da pré-compilação para que init() carregue corretamente.

Build de CI

- run: wasm-pack build --target bundler --release
- run: cd pkg && npm publish --access public

Armadilhas

Esqueceu await init() - Funções falham com erros opacos. Correção: Sempre aguarde init() na inicialização do aplicativo.
Alvo errado - Os caminhos de importação web vs bundler diferem. Correção: Combine o alvo com a documentação do seu bundler.
Pasta pkg enorme - Builds de depuração incham os tarballs npm. Correção: Use --release e adicione pkg/ ao .gitignore se estiver reconstruindo em CI.
Tipo MIME em servidores estáticos - .wasm servido como application/octet-stream falha. Correção: Configure application/wasm.
Top-level await - Bundlers mais antigos têm problemas com a inicialização WASM. Correção: import() dinâmico dentro de funções assíncronas.

Alternativas

Alternativa	Use Quando	Não Use Quando
`cargo component build`	Pacotes do Component Model	Aplicativos clássicos wasm-bindgen para navegador
`wasm-bindgen-cli` manual	Pipelines de build personalizados	Você quer metadados npm gerados
Tags de script CDN	Protótipos rápidos	Aplicativos frontend baseados em npm

FAQs

Layout de Monorepo?

Crate Rust em crates/mylib, wasm-pack build gera saída em crates/mylib/pkg, o frontend depende via protocolo de workspace.

Tipos TypeScript?

wasm-pack gera .d.ts automaticamente. Confirme ou regenere em CI.

Workspaces e hoisting?

O hoisting pode quebrar caminhos relativos de .wasm. Fixe o pacote WASM como dependência direta.

Frameworks SSR?

WASM roda apenas no lado do cliente. Controle as importações com typeof window !== "undefined".

Webpack async WASM?

Habilite experiments.asyncWebAssembly na configuração do webpack 5.

Alinhamento de versão?

Mantenha as versões do crate wasm-bindgen e da CLI correspondentes às notas de lançamento do wasm-pack.

Registro npm privado?

Publique pkg/ no seu registro; os consumidores instalam como qualquer pacote npm.

Flags de recursos?

Passe -- --features foo para encaminhar recursos do Cargo através do wasm-pack.

Otimizar com wasm-opt?

wasm-pack pode executar otimizações do binaryen. Habilite na configuração do wasm-pack para saída menor.

Testar o pkg?

Use wasm-pack test --headless com chromedriver ou playwright.

Relacionado

wasm-bindgen - Ponte JS/Rust
Noções Básicas de WebAssembly - alvos de build
Desempenho e Tamanho - otimização binária
Frameworks Frontend (Leptos / Yew) - integração de framework

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

wasm-pack & Bundling

Construa e distribua pacotes WASM consumíveis por npm com wasm-pack e bundlers de frontend.

Receita

cargo install wasm-pack
wasm-pack build --target bundler --release

pkg/
  mylib.js          # Cola JS
  mylib_bg.wasm     # Binário WASM
  mylib.d.ts        # Tipos TypeScript
  package.json      # Metadados npm

Quando usar isso: Publicar Rust WASM para npm para consumidores React, Vite ou webpack.

Exemplo de Trabalho

// package.json (projeto frontend raiz)
{
  "dependencies": {
    "mylib": "file:../mylib/pkg"
  }
}

// src/worker.ts
import init, { process_data } from "mylib";
 
export async function run(input: Uint8Array) {
  await init();
  return process_data(input);
}

# Rust crate Cargo.toml
[package]
name = "mylib"
version = "0.1.0"
edition = "2024"
 
[lib]
crate-type = ["cdylib"]
 
[dependencies]
wasm-bindgen = "0.2"

O que isso demonstra:

wasm-pack emite um pacote npm completo em pkg/
--target bundler é adequado para tree-shaking do webpack/vite
init() deve ser executado antes de chamar as funções exportadas
Links de caminho file: locais durante o desenvolvimento

Mergulho Profundo

Alvos do wasm-pack

Alvo	Consumidor
`web`	`<script type="module">` do navegador
`bundler`	webpack, vite, parcel
`nodejs`	Node.js com acesso a fs
`deno`	Importações Deno

Configuração do Vite

// vite.config.ts
export default {
  optimizeDeps: {
    exclude: ["mylib"],
  },
};

Exclua pacotes WASM da pré-compilação para que init() carregue corretamente.

Build de CI

- run: wasm-pack build --target bundler --release
- run: cd pkg && npm publish --access public

Armadilhas

Esqueceu await init() - Funções falham com erros opacos. Correção: Sempre aguarde init() na inicialização do aplicativo.
Alvo errado - Os caminhos de importação web vs bundler diferem. Correção: Combine o alvo com a documentação do seu bundler.
Pasta pkg enorme - Builds de depuração incham os tarballs npm. Correção: Use --release e adicione pkg/ ao .gitignore se estiver reconstruindo em CI.
Tipo MIME em servidores estáticos - .wasm servido como application/octet-stream falha. Correção: Configure application/wasm.
Top-level await - Bundlers mais antigos têm problemas com a inicialização WASM. Correção: import() dinâmico dentro de funções assíncronas.

Alternativas

Alternativa	Use Quando	Não Use Quando
`cargo component build`	Pacotes do Component Model	Aplicativos clássicos wasm-bindgen para navegador
`wasm-bindgen-cli` manual	Pipelines de build personalizados	Você quer metadados npm gerados
Tags de script CDN	Protótipos rápidos	Aplicativos frontend baseados em npm

FAQs

Layout de Monorepo?

Crate Rust em crates/mylib, wasm-pack build gera saída em crates/mylib/pkg, o frontend depende via protocolo de workspace.

Tipos TypeScript?

wasm-pack gera .d.ts automaticamente. Confirme ou regenere em CI.

Workspaces e hoisting?

O hoisting pode quebrar caminhos relativos de .wasm. Fixe o pacote WASM como dependência direta.

Frameworks SSR?

WASM roda apenas no lado do cliente. Controle as importações com typeof window !== "undefined".

Webpack async WASM?

Habilite experiments.asyncWebAssembly na configuração do webpack 5.

Alinhamento de versão?

Mantenha as versões do crate wasm-bindgen e da CLI correspondentes às notas de lançamento do wasm-pack.

Registro npm privado?

Publique pkg/ no seu registro; os consumidores instalam como qualquer pacote npm.

Flags de recursos?

Passe -- --features foo para encaminhar recursos do Cargo através do wasm-pack.

Otimizar com wasm-opt?

wasm-pack pode executar otimizações do binaryen. Habilite na configuração do wasm-pack para saída menor.

Testar o pkg?

Use wasm-pack test --headless com chromedriver ou playwright.

Relacionado

wasm-bindgen - Ponte JS/Rust
Noções Básicas de WebAssembly - alvos de build
Desempenho e Tamanho - otimização binária
Frameworks Frontend (Leptos / Yew) - integração de framework

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

wasm-pack & Bundling

Buscar na documentação

wasm-pack & Bundling