Parcel 1.x wasm-bindgen plugin for Rust

Common errors

• Error: Cannot find module 'path/to/Cargo.toml'

  cause Parcel 1.x cannot locate or process the Rust crate defined by the `Cargo.toml` path, often due to incorrect pathing, missing `parcel-plugin-wasm.rs` in `devDependencies`, or issues with `cargo`/`wasm-pack` installation preventing the WASM module from being generated.
  fix Verify the path to `Cargo.toml` is correct. Ensure `parcel-plugin-wasm.rs` is listed in `devDependencies` in `package.json`. Confirm that `cargo` and `wasm-pack` are installed and working. Check Parcel's build logs for underlying Rust/Wasm compilation errors.

• error: linker `link.exe` not found

  cause Rust compilation failed because the linker required by the Rust toolchain is not found. This often occurs on Windows systems if a C++ build environment (like MSVC) is not installed or configured correctly.
  fix Install the appropriate C++ build tools for your platform, usually by installing 'Desktop development with C++' from Visual Studio Installer on Windows, or `build-essential` on Linux/macOS. Ensure the Rust toolchain is properly configured for your target.

• 🚨 Error writing to cache: ENOENT: no such file or directory, stat 'build.rs'

  cause This error, reported in issue #37 on the plugin's GitHub, indicates a problem with Parcel's caching mechanism interacting with Rust's build system, possibly related to `build.rs` files or project structure.
  fix Try clearing Parcel's cache (`rm -rf .parcel-cache dist`) and rebuilding. Review your Rust project's `build.rs` or `Cargo.toml` for any non-standard configurations. This may also be a plugin-specific bug that has not been resolved.

Warnings

• breaking This plugin targets `parcel-bundler` (Parcel 1.x), which is officially unmaintained. It is not compatible with Parcel 2.x. Using it with Parcel 2.x will lead to build failures or incorrect behavior. Parcel 2.x has its own native support for Rust/Wasm via `@parcel/transformer-rust`.
  Fix: For new projects or migration, use Parcel 2.x and its built-in `@parcel/transformer-rust`. For existing Parcel 1.x projects, consider migrating to Parcel 2.x or remaining on Parcel 1.x with caution regarding security and updates.
• gotcha Requires external tools `cargo` and `wasm-pack` to be installed globally on the system where Parcel is running. Missing these tools will result in compilation errors during the Parcel build process.
  Fix: Ensure `cargo` (Rust toolchain) and `wasm-pack` are installed and available in your system's PATH. Check installation instructions for Rust and `wasm-pack`.
• gotcha The `WASM_PACK_PROFILE` environment variable is used to control the `wasm-pack build` profile (e.g., `dev`, `release`). This variable needs to be set in the shell before running Parcel commands.
  Fix: Set the environment variable explicitly before your Parcel command, for example: `WASM_PACK_PROFILE=dev parcel src/index.html` or `cross-env WASM_PACK_PROFILE=dev parcel src/index.html` for cross-platform compatibility.

Install

• npm install parcel-plugin-wasm.rs npm
• yarn add parcel-plugin-wasm.rs yarn
• pnpm add parcel-plugin-wasm.rs pnpm

Imports

• foo

  import { foo } from 'path/to/Cargo.toml'

  Named imports are used for functions exported from Rust via `#[wasm_bindgen]`.
• lib

  import lib from 'path/to/Cargo.toml'

  Default import provides access to the raw WASM module and its exports, including `memory`.
• WasmModule

  import type { WasmModule } from 'path/to/Cargo.toml'

  TypeScript type imports for the generated WASM module structure.

Quickstart

Demonstrates a basic setup for integrating a Rust project compiled to WebAssembly with Parcel 1.x using `parcel-plugin-wasm.rs`. It includes the necessary Rust, JavaScript, and `package.json` configurations to greet a user from WebAssembly.

/* file: my-crate/src/lib.rs */
extern crate wasm_bindgen;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn greet(name: &str) -> String {
  format!("Hello, {}!", name)
}

/* file: src/index.js */
import { greet } from '../my-crate/Cargo.toml';

document.getElementById('app').innerHTML = `
  <h1>Rust + WebAssembly in Parcel 1.x</h1>
  <p>${greet('Parcel user')}</p>
`;

console.log('Greeting from Rust:', greet('world'));

/* file: package.json (relevant part) */
{
  "name": "my-parcel-wasm-app",
  "version": "1.0.0",
  "devDependencies": {
    "parcel-bundler": "^1.12.5",
    "parcel-plugin-wasm.rs": "^1.3.0"
  },
  "scripts": {
    "start": "parcel src/index.html",
    "build": "parcel build src/index.html"
  }
}

/* file: src/index.html */
<!DOCTYPE html>
<html>
<head>
  <title>Parcel WASM Example</title>
</head>
<body>
  <div id="app"></div>
  <script src="index.js"></script>
</body>
</html>