rsbuild-plugin-wasmpack

rsbuild-plugin-wasmpack is a plugin for Rsbuild that enables you to compile Rust crates into WebAssembly (Wasm) using wasm-pack. It simplifies integration of Rust code into web applications with support for hot-reloading, crate aliasing, and automatic Rust toolchain management.

Table of Contents

• rsbuild-plugin-wasmpack
  • Table of Contents
  • Demo
  • Prerequisites
  • Installation
    • npm
    • bun
    • pnpm
    • yarn
  • Usage
    • Example rsbuild.config.js
    • Example usage
  • Configuration Options
    • crates (required)
    • wasmpackPath (optional)
    • pkgsDir (optional)
    • aliasPkgDir (optional)
    • autoInstallWasmPack (optional)
    • autoInstallRust (optional)

Demo

The demo above showcases live reloading of compiled WebAssembly as Rust code is updated.

Prerequisites

Ensure the following are available in your environment:

• wasm-pack

  cargo install wasm-pack

• A working Rsbuild setup in your project.

If you don’t have Rust or wasm-pack, the plugin can optionally install them for you (see Configuration Options).

Installation

Install using your package manager of choice:

npm

npm install --save-dev rsbuild-plugin-wasmpack

bun

bun add -d rsbuild-plugin-wasmpack

pnpm

pnpm add -D rsbuild-plugin-wasmpack

yarn

yarn add -D rsbuild-plugin-wasmpack

Usage

Once installed, you can add the plugin to your rsbuild configuration. Here’s an example configuration for compiling a Rust crate to WebAssembly:

Example rsbuild.config.js

import { defineConfig } from "@rsbuild/core";
import { pluginWasmPack } from "rsbuild-plugin-wasmpack";

export default defineConfig({
  plugins: [
    pluginWasmPack({
      crates: [
        {
          path: "crate1",
          target: "web",
          liveReload: false // Optional if false disable liveReload (defaults to true).
        },
        {
          path: "crate2",
          target: "web",
          profileOnDev: "profiling",
          profileOnProd: "release",
        },
        {
          path: "crate3",
          target: "web",
          features: ["serde"], // Optional (defaults to none)
          defaultFeatures: false // Optional (defaults to true)
        },
      ],
      wasmpackPath: "~/.cargo/bin/wasm-pack", // Optional (this can be loaded from envfile)
      pkgsDir: "pkgs", // Optional (default is "pkgs")
      aliasPkgDir: true, // Optional (default is true)
      autoInstallWasmPack: true, // Optional

      // Optional Rust auto-install setup
      autoInstallRust: true,
      rustToolchainOptions: {
        defaultToolchain: "stable",
        profile: "minimal",
        components: ["clippy"],
        targets: ["wasm32-unknown-unknown"],
      },
    }),
  ],
});

💡 When aliasPkgDir is enabled, an alias will be created that maps @pkgs/* to the contents of pkgsDir (default is "pkgs"). The plugin also attempts to update your tsconfig.json with the correct alias. Be sure to check it manually if the automatic patch fails.

Example usage

import initializeRust1 from "@pkgs/rust1"; // Maps to pkgs/rust1 based on pkgsDir and aliasPkgDir
import initializeRust2 from "@pkgs/rust2";

// 🔔 Note: This import alias only works if `aliasPkgDir` is enabled.
// If disabled, you must import from the actual relative path (e.g., "../pkgs/rust1").

initializeRust1().then((rust1) => {
  rust1.greet("World1");
});

initializeRust2().then((rust2) => {
  rust2.greet("World2");
});

Configuration Options

crates (required)

An array of objects representing the Rust crates you want to compile. Each object should have the following properties:

• path (string): The path to your Rust crate or project. This is typically the folder containing Cargo.toml.

• target ("web" | "nodejs" | "deno"): The WebAssembly target.

• profileOnDev ("dev"| "profiling" | "release"): The profile to use when building the crate in development mode. This is optional and defaults to dev.

• profileOnProd ("dev"| "profiling" | "release"): The profile to use when building the crate in production mode. This is optional and defaults to release.

• features A list of Cargo features to explicitly enable when building the crate. This maps directly to --features flag. Example: ["serde", "simd", "unstable-api"].

• defaultFeatures (true | false) Controls whether Cargo’s default features are enabled when building the crate. If false the --no-default-features flag will be passed.

• liveReload (true | false) If true changes to source files automatically trigger a rebuild and reload the page. Defaults to true

• stripWasm Profiles for which the output .wasm binary should be stripped using wabt. Example: stripBinary: ["release"].

wasmpackPath (optional)

Custom path to the wasm-pack binary. Defaults to the standard Cargo bin path (~/.cargo/bin/wasm-pack).

pkgsDir (optional)

The directory where compiled Wasm output will be written. Defaults to "pkgs".

aliasPkgDir (optional)

If enabled (true by default), the plugin will:

• Create an alias mapping @pkgs to the pkgsDir
• Attempt to update your tsconfig.json with the following path:

{
  "compilerOptions": {
    "paths": {
      "@pkgs/*": ["./pkgs/*"]
    }
  }
}

⚠️ You may need to manually verify this mapping if automatic insertion fails.

autoInstallWasmPack (optional)

If true, the plugin will install wasm-pack via Cargo if it's not found in your system.

autoInstallRust (optional)

Configure how the Rust toolchain should be handled.