DOCSEARCHbyAlgolia
Submit Docs

wasm-pack

repository·master·Indexed 27 days ago

https://github.com/wasm-bindgen/wasm-pack

A workflow tool for building and working with Rust-generated WebAssembly that interops with JavaScript in the browser or Node.js. It provides CLI commands to scaffold projects (new), compile Rust to WASM and generate JS glue code (build), run browser tests (test), and create or publish packages to the npm registry (pack, publish). It supports multiple compilation targets including bundler, nodejs, web, no-modules, and deno, and allows configuration via Cargo.toml for optimization and wasm-bindgen settings.

Tokens
10.7K
Snippets
46
Records
107
Agent score
92%

What's inside wasm-pack

  1. Overview of wasm-pack

    master
    wasm-pack is a tool designed to be a one-stop shop for building and working with Rust-generated WebAssembly. It facilitates interoperability between WebAssembly and JavaScript, whether running in a web browser or in Node.js. It enables you to build Rust-generated WebAssembly packages that can be published to the npm registry or integrated into existing JavaScript workflows, such as those using webpack.

  2. About wasm-pack

    master
    wasm-pack is a workflow tool for building and working with Rust-generated WebAssembly. It is designed to facilitate interoperability between Rust and JavaScript, allowing you to build WebAssembly packages for use in the browser or with Node.js. It enables you to create packages suitable for publishing to the npm registry or integrating into existing JavaScript workflows like webpack.

  4. Set up a local development environment for wasm-pack

    master

    To run wasm-pack locally from the source code, follow these steps:

    1. Fork and clone the wasm-bindgen/wasm-pack repository.
    2. Ensure [node/npm] is installed on your system.
    3. Navigate to the project root: cd wasm-pack.
    4. Run the tool using Cargo: cargo run.

    To test specific command line arguments, use the -- separator to pass them to the binary: cargo run -- <args>

    cd wasm-pack
cargo run -- init /tests/fixtures/js-hello-world --scope=ag_dubs

  5. Build hybrid applications with Webpack using the rust-webpack-template

    master

    To build a hybrid application using WebAssembly and Webpack, use the rust-webpack-template. This workflow allows you to integrate Rust-based WebAssembly modules into a standard Webpack-based JavaScript application.

    Before starting, ensure you have completed the Prerequisites for wasm-pack.

    https://github.com/drager/rust-webpack-template

  6. Build 64-bit WebAssembly (`wasm64-unknown-unknown`)

    master

    To produce a memory64 binary, you must target wasm64-unknown-unknown. Since this is a tier-3 target, you must provide a nightly toolchain and build std from source.

    Option 1: Cargo Config (Recommended) In .cargo/config.toml:

    [build]
target = "wasm64-unknown-unknown"

[unstable]
build-std = ["std", "panic_abort"]

    Option 2: Extra Cargo Arguments Pass the target and build-std flags directly to cargo via wasm-pack:

    wasm-pack build -- --target wasm64-unknown-unknown -Z build-std=std,panic_abort

    Option 3: Environment Variable

    CARGO_BUILD_TARGET=wasm64-unknown-unknown wasm-pack build

    When wasm-pack detects a wasm64-* triple, it automatically verifies the nightly toolchain and passes --enable-memory64 to wasm-opt.

    # .cargo/config.toml
[build]
target = "wasm64-unknown-unknown"

[unstable]
build-std = ["std", "panic_abort"]

  7. Create a new RustWasm project with wasm-pack new

    master

    Use the wasm-pack new command to scaffold a new RustWasm project. This command uses cargo-generate to create the project structure.

    By default, it uses the wasm-bindgen/wasm-pack template (which includes the wasm-pack-template cargo-generate template).

    wasm-pack new <name> --template <template> --mode <normal|noinstall|force>

  10. Configure panic strategy with `--panic-unwind`

    master

    By default, Rust panics in WebAssembly use panic=abort, which terminates the instance. Using the --panic-unwind flag allows panics to be caught at FFI boundaries and converted into JavaScript exceptions.

    Requirements:

    • Requires the nightly toolchain.
    • wasm-pack will attempt to install the nightly toolchain, rust-src, and the wasm32-unknown-unknown target via rustup if they are missing.

    Note: To actually catch the exception in JavaScript, you must use runtime glue from your bindings layer (like wasm-bindgen's catch-unwind support).

    wasm-pack build --panic-unwind

  11. Build and run a Rust Webpack project

    master

    After setting up your Rust crate and JavaScript entry point, use the following commands in the project root to build and preview your application:

    1. Build: Run npm run build to compile the Rust code to WebAssembly and bundle the JavaScript using Webpack. This creates a dist directory.
    2. Start: Run npm start to launch the webpack-dev-server.
    3. View: Navigate to http://localhost:8080 in your browser.
    npm run build
npm start

  12. Manually add the wasm32-unknown-unknown target for non-Rustup setups

    master

    If you are not using rustup, wasm-pack cannot automatically install the required wasm32-unknown-unknown target. You must manually download the target matching your specific rustc version and place it in your Rust sysroot's lib/rustlib/ directory.

    Note: This process requires the downloaded target to match your exact rustc release to avoid incompatibility.