@waynevanson/vite-plugin-cargo 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 Wayne Van Son
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# vite-plugin-cargo
+
+A Vite plugin that seamlessly integrates Rust crates into your frontend project by compiling them to WebAssembly via `cargo` and `wasm-bindgen`.
+
+## Features
+
+- **Zero-Config Compiling**: Automatically detects the closest `Cargo.toml`.
+- **WASM-Bindgen Integration**: Generates the necessary JS glue code automatically.
+- **TypeScript Support**: Automatically generates and syncs `.d.ts` files for your Rust exports.
+- **HMR Support**: Works with Vite's dev server.
+- **Release Optimization**: Automatically uses `--release` builds during `vite build`.
+
+## Prerequisites
+
+You must have the following installed on your system:
+
+1. [Rust and Cargo](https://rustup.rs/)
+2. `wasm32-unknown-unknown` target: `rustup target add wasm32-unknown-unknown`
+3. [`wasm-bindgen-cli`](<https://www.google.com/search?q=%5Bhttps://github.com/rustwasm/wasm-bindgen%5D(https://github.com/rustwasm/wasm-bindgen)>): `cargo install -f wasm-bindgen-cli`
+
+## Installation
+
+```bash
+npm install vite-plugin-cargo --save-dev
+
+```
+
+## Usage
+
+### 1. Configure Vite
+
+Add the plugin to your `vite.config.ts`. You must specify which files should be treated as Rust entrypoints using a glob pattern.
+
+```typescript
+import { defineConfig } from "vite";
+import { cargo } from "vite-plugin-cargo";
+
+export default defineConfig({
+  plugins: [
+    cargo({
+      includes: ["src/lib.rs"], // Files to treat as Cargo entrypoints
+    }),
+  ],
+});
+```
+
+### 2. Prepare your Rust code
+
+Ensure your Rust crate is configured as a `cdylib`.
+
+**Cargo.toml**
+
+```toml
+[package]
+name = "my-rust-lib"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wasm-bindgen = "0.2"
+
+```
+
+**src/lib.rs**
+
+```rust
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+```
+
+### 3. Import in JS/TS
+
+```typescript
+import { greet } from "./src/lib.rs";
+
+console.log(greet("Vite"));
+```
+
+## Configuration Options
+
+### Base Configuration
+
+| Option         | Type      | Description                                      |
+| :------------- | :-------- | :----------------------------------------------- |
+| `includes`     | `string   | string[]` Glob pattern of Rust files to process. |
+| `browserOnly`  | `boolean` | (Optional) Passes `--browser` to `wasm-bindgen`. |
+| `noTypescript` | `boolean` | (Optional) Disables `.d.ts` generation.          |
+
+### Rust Features
+
+Additionally, one of the following configurations can be used with the base.
+
+| Option              | Type       | Description                                  |
+| :------------------ | :--------- | :------------------------------------------- |
+| `features`          | `string[]` | (Optional) List of Cargo features to enable. |
+| `noDefaultFeatures` | `boolean`  | (Optional) Disable default Cargo features.   |
+
+| Option        | Type      | Description                           |
+| :------------ | :-------- | :------------------------------------ |
+| `allFeatures` | `boolean` | (Optional) Enable all Cargo features. |
+
+---
+
+## How it works
+
+Transformation pipeline:
+
+```js
+`.rs` -> `.wasm` + `.js` + `.d.ts`
+```
+
+1. **Detection**: The plugin matches files via the `includes` glob.
+2. **Metadata**: It runs `cargo metadata` to find the correct `cdylib` target.
+3. **Compilation**: Runs `cargo build --target wasm32-unknown-unknown`.
+4. **Binding**: Runs `wasm-bindgen` on the resulting `.wasm` file to a local cache in `node_modules/.cache`.
+5. **Resolution**: Injects the generated JavaScript glue code into your Vite bundle.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import picomatch from "picomatch";
+import type { Plugin } from "vite";
+export type VitePluginCargoOptions = {
+    includes: picomatch.Glob;
+    browserOnly?: boolean;
+    noTypescript?: boolean;
+} & ({
+    noDefaultFeatures?: boolean;
+    features?: Array<string>;
+} | {
+    allFeatures: true;
+});
+export declare function cargo(pluginOptions: VitePluginCargoOptions): Plugin<never>;

package/dist/index.js

@@ -0,0 +1,140 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import picomatch from "picomatch";
+import * as v from "valibot";
+// todo: Replace all schema with only parsing what we need to searching.
+const MetadataSchema = (options) => v.nonNullish(v.pipe(v.object({
+    packages: v.array(v.pipe(v.object({
+        manifest_path: v.string(),
+        targets: v.array(v.object({
+            kind: v.array(v.string()),
+            name: v.string(),
+            src_path: v.string(),
+        })),
+    }), v.transform((package_) => package_.targets.flatMap((target) => target.kind.flatMap((kind) => ({
+        manifest_path: package_.manifest_path,
+        ...target,
+        kind,
+    })))))),
+}), v.transform((packages) => packages.packages.flat()), v.findItem((metadata) => v.is(v.object({
+    manifest_path: v.literal(options.project),
+    name: v.string(),
+    src_path: v.literal(options.id),
+    kind: v.literal("cdylib"),
+}), metadata))));
+function getClosestCargoProject(id) {
+    return execFileSync("cargo", ["locate-project", "--message-format=plain"], {
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf-8",
+        cwd: path.dirname(id),
+    }).trim();
+}
+// todo: what to do there's multiple libraries for the same file?
+// Maybe add config force user to resolve this.
+function ensureRustLibraryMetadata(options) {
+    // validate if the file is the entrypoint to a cdylib target as rust lib
+    const metacontent = execFileSync("cargo", ["metadata", "--no-deps", "--format-version=1"], {
+        cwd: path.dirname(options.id),
+        encoding: "utf-8",
+    }).trim();
+    // find the right library from our file
+    const metadata = v.parse(MetadataSchema(options), JSON.parse(metacontent));
+    return metadata;
+}
+function compileLibrary(options, isServe) {
+    // create `.wasm` from `.rs`
+    const ndjson = execFileSync("cargo", [
+        "build",
+        "--lib",
+        "--target=wasm32-unknown-unknown",
+        "--message-format=json",
+        "--color=never",
+        "--quiet",
+        isServe || "--release",
+    ].filter((a) => typeof a === "string"), {
+        cwd: path.dirname(options.id),
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const json = ndjson
+        .trim()
+        .split("\n")
+        .map((json) => JSON.parse(json));
+    // find the `.wasm` file
+    const filename = json
+        .filter((a) => a?.reason === "compiler-artifact")
+        .filter((a) => a?.manifest_path === options.project)[0]?.filenames?.[0];
+    return filename;
+}
+// 1. Plugin for Rust -> WASM -> WASM + ESM
+// Dependencies:
+// 1. `cargo`
+// 2. `wasm_bindgen`
+export function cargo(pluginOptions) {
+    const matches = picomatch(pluginOptions.includes, { contains: true });
+    const typescript = !(pluginOptions?.noTypescript ?? false);
+    let isServe = false;
+    const libraries = new Map();
+    return {
+        name: "vite-plugin-cargo",
+        configResolved(config) {
+            isServe = config.command === "serve";
+        },
+        async resolveId(source, importer) {
+            // check if this import came from one of our entrypoints
+            const entry = libraries
+                .values()
+                .find((library) => library.id === importer);
+            if (entry === undefined) {
+                return null;
+            }
+            // ensure source is relative to wasm_bindgen output dir
+            return path.resolve(entry.outDir, source);
+        },
+        async transform(_code, id) {
+            if (!matches(id)) {
+                return null;
+            }
+            const project = getClosestCargoProject(id);
+            const options = { id, project };
+            const metadata = ensureRustLibraryMetadata(options);
+            const hash = createHash("sha256")
+                .update(`${project}:${id}`)
+                .digest("hex");
+            const outDir = path.resolve(`node_modules/.cache/vite-plugin-cargo/${hash}`);
+            libraries.set(hash, { id, outDir, project });
+            const wasm = compileLibrary(options, isServe);
+            // create `.js` from `.wasm`
+            //
+            // `.js` and `.wasm` files are created in outDir,
+            // and added to dependency graph from imports in the `.js` entrypoint.
+            execFileSync("wasm-bindgen", [
+                "--target=bundler",
+                `--out-dir=${outDir}`,
+                isServe && `--debug`,
+                typescript || `--no-typescript`,
+                pluginOptions.browserOnly && `--browser`,
+                wasm,
+            ].filter((a) => typeof a === "string"));
+            const entrypoint = path.resolve(outDir, `${metadata.name}.js`);
+            const content = await this.fs.readFile(entrypoint, { encoding: "utf8" });
+            // `.d.ts` from `wasm_bindgen` aren't read I believe, so we emit them ourselves.
+            // todo: only emit the files we load. Currently we assume they're all loaded.
+            if (typescript) {
+                // add `.d.ts` to files
+                const filenames = await this.fs.readdir(outDir);
+                await Promise.all(filenames
+                    .filter((filename) => filename.endsWith(".d.ts"))
+                    .map(async (filename) => await this.load({ id: path.resolve(outDir, filename) })));
+                // copy <name>.d.ts to the <id>.d.ts so user gets type definitions
+                const source = path.join(outDir, `${metadata.name}.d.ts`);
+                const target = `${id}.d.ts`;
+                await this.fs.copyFile(source, target);
+            }
+            return {
+                code: content,
+            };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@waynevanson/vite-plugin-cargo",
+	"version": "1.0.0",
+	"description": "Import wasm_bingen compatible Rust to JavaScript via Vite",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"type": "module",
+	"repository": {
+		"url": "https://github.com/waynevanson/vite-plugin-cargo"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"vite-plugin"
+	],
+	"scripts": {
+		"build": "tsc",
+		"prepublishOnly": "tsc"
+	},
+	"author": "Wayne Van Son",
+	"license": "MIT",
+	"packageManager": "pnpm@10.27.0",
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.13",
+		"@types/node": "^24.10.9",
+		"@types/picomatch": "^4.0.2",
+		"typescript": "^5.9.3",
+		"vite": "^7.3.1",
+		"vitest": "^4.0.18"
+	},
+	"dependencies": {
+		"picomatch": "^4.0.3",
+		"valibot": "^1.2.0"
+	},
+	"peerDependencies": {
+		"vite": "^7.3.1"
+	},
+	"peerDependenciesMeta": {
+		"vite": {
+			"optional": false
+		}
+	}
+}