tauri-js-runtime

---
name: tauri-js-runtime
description: Add JavaScript runtime backend capabilities to Tauri v2 desktop apps. Covers both using the tauri-plugin-js plugin and building from scratch. Use when integrating Bun, Node.js, or Deno as backend processes in Tauri, setting up type-safe RPC between frontend and JS runtimes, creating Electron-like architectures in Tauri, or managing child processes with stdio communication.
version: 1.0.0
license: MIT
metadata:
  domain: desktop-apps
  tags:
    - tauri
    - bun
    - node
    - deno
    - rpc
    - kkrpc
    - electron-alternative
    - process-management
    - compiled-sidecar
---

# Tauri + JS Runtime Integration

Give Tauri apps full JS runtime backends (Bun, Node.js, Deno) with type-safe bidirectional RPC. This covers two approaches: using the `tauri-plugin-js` plugin, and building the integration from scratch.

## When to Use

- User wants to run JS/TS backend code from a Tauri desktop app
- User asks about Electron alternatives or "Electron-like" features in Tauri
- User needs to spawn/manage child processes (Bun, Node, Deno) from Rust
- User wants type-safe RPC between a Tauri webview and a JS runtime
- User needs stdio-based IPC between Rust and a child process
- User asks about kkrpc integration with Tauri
- User wants multi-window apps where windows share backend processes
- User needs runtime detection (which runtimes are installed, paths, versions)
- User wants to ship a Tauri app without requiring JS runtimes on user machines (compiled sidecars)
- User asks about `bun build --compile` or `deno compile` with Tauri

## Core Architecture

```
Frontend (Webview)  <-- Tauri Events -->  Rust Core  <-- stdio -->  JS Runtime
```

- **Rust** spawns child processes, pipes their stdin/stdout/stderr, and relays data via Tauri events
- **Rust never parses RPC payloads** — it forwards raw newline-delimited strings
- **kkrpc** handles the RPC protocol on both ends (frontend webview + backend runtime)
- **Frontend IO adapter** bridges Tauri events to kkrpc's IoInterface (read/write/on/off)
- **Multi-window** works because all windows receive the same Tauri events; kkrpc request IDs handle routing

## Approach A: Using tauri-plugin-js (Recommended)

The plugin handles process management, stdio relay, event emission, and provides a frontend npm package with typed wrappers and an IO adapter.

### Step 1: Install

**Rust** — add to `src-tauri/Cargo.toml`:
```toml
[dependencies]
tauri-plugin-js = "0.1"
```

**Frontend** — install npm packages:
```bash
pnpm add tauri-plugin-js-api kkrpc
```

### Step 2: Register the plugin

In `src-tauri/src/lib.rs`:
```rust
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_js::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### Step 3: Add permissions

In `src-tauri/capabilities/default.json`:
```json
{
  "permissions": [
    "core:default",
    "js:default"
  ]
}
```

### Step 4: Define a shared API type

Create a type definition shared between frontend and backend workers:
```typescript
// backends/shared-api.ts
export interface BackendAPI {
  add(a: number, b: number): Promise<number>;
  echo(message: string): Promise<string>;
  getSystemInfo(): Promise<{
    runtime: string;
    pid: number;
    platform: string;
    arch: string;
  }>;
}
```

### Step 5: Write backend workers

Each runtime has its own IO adapter from kkrpc:

**Bun** (`backends/bun-worker.ts`):
```typescript
import { RPCChannel, BunIo } from "kkrpc";
import type { BackendAPI } from "./shared-api";

const api: BackendAPI = {
  async add(a, b) { return a + b; },
  async echo(msg) { return `[bun] ${msg}`; },
  async getSystemInfo() {
    return { runtime: "bun", pid: process.pid, platform: process.platform, arch: process.arch };
  },
};

const io = new BunIo(Bun.stdin.stream());
const channel = new RPCChannel(io, { expose: api });
```

**Node** (`backends/node-worker.mjs`):
```javascript
import { RPCChannel, NodeIo } from "kkrpc";

const api = {
  async add(a, b) { return a + b; },
  async echo(msg) { return `[node] ${msg}`; },
  async getSystemInfo() {
    return { runtime: "node", pid: process.pid, platform: process.platform, arch: process.arch };
  },
};

const io = new NodeIo(process.stdin, process.stdout);
const channel = new RPCChannel(io, { expose: api });
```

**Deno** (`backends/deno-worker.ts`):
```typescript
import { DenoIo, RPCChannel } from "npm:kkrpc/deno";
import type { BackendAPI } from "./shared-api.ts";  // .ts extension required by Deno

const api: BackendAPI = {
  async add(a, b) { return a + b; },
  async echo(msg) { return `[deno] ${msg}`; },
  async getSystemInfo() {
    return { runtime: "deno", pid: Deno.pid, platform: Deno.build.os, arch: Deno.build.arch };
  },
};

const io = new DenoIo(Deno.stdin.readable);
const channel = new RPCChannel(io, { expose: api });
```

### Step 6: Frontend — spawn and call

```typescript
import { spawn, createChannel, onStdout, onStderr, onExit } from "tauri-plugin-js-api";
import type { BackendAPI } from "../backends/shared-api";

// Spawn
const cwd = await resolve("..", "backends");  // from @tauri-apps/api/path
await spawn("my-worker", { runtime: "bun", script: "bun-worker.ts", cwd });

// Events
onStdout("my-worker", (data) => console.log(data));
onStderr("my-worker", (data) => console.error(data));
onExit("my-worker", (code) => console.log("exited", code));

// Type-safe RPC
const { api } = await createChannel<Record<string, never>, BackendAPI>("my-worker");
const result = await api.add(5, 3);  // compile-time checked
```

### Step 7: Compiled binary sidecars (no runtime on user machine)

Both Bun and Deno can compile TS workers into standalone executables. The compiled binaries preserve stdin/stdout behavior, so kkrpc works unchanged.

**Compile with target triple suffix:**
```bash
TARGET=$(rustc -vV | grep host | cut -d' ' -f2)

# Bun — compile directly from the project directory
bun build --compile --minify backends/bun-worker.ts --outfile src-tauri/binaries/bun-worker-$TARGET

# Deno — MUST compile from a separate Deno package (see pitfall #8 below)
deno compile --allow-all --output src-tauri/binaries/deno-worker-$TARGET path/to/deno-package/main.ts
```

**Configure Tauri to bundle sidecars** in `src-tauri/tauri.conf.json`:
```json
{
  "bundle": {
    "externalBin": ["binaries/bun-worker", "binaries/deno-worker"]
  }
}
```

Tauri automatically appends the current platform's triple when resolving `externalBin` paths, so the binary is included in the app bundle and runs on the user's machine without any runtime installed.

**Spawn with `sidecar` instead of `runtime`:**
```typescript
import { spawn, createChannel } from "tauri-plugin-js-api";

await spawn("compiled-worker", { sidecar: "bun-worker" });

// RPC works identically
const { api } = await createChannel<Record<string, never>, BackendAPI>("compiled-worker");
await api.add(5, 3); // => 8
```

**Key points:**
- `config.sidecar` resolves the binary via Tauri's sidecar mechanism — looks next to the app executable, tries both plain name (production) and `{name}-{triple}` (development)
- The same worker TS source compiles into a binary that runs identically to the runtime-based version
- `getSystemInfo()` still reports `runtime: "bun"` or `runtime: "deno"` — the runtime is embedded in the binary
- No filesystem path resolution needed on the frontend — just pass the sidecar name

### Step 8: Runtime detection (optional)

```typescript
import { detectRuntimes, setRuntimePath } from "tauri-plugin-js-api";

const runtimes = await detectRuntimes();
// [{ name: "bun", available: true, version: "1.2.0", path: "/usr/local/bin/bun" }, ...]

// Override path for a specific runtime
await setRuntimePath("node", "/custom/path/to/node");
```

### Plugin API Summary

| Command | Description |
|---------|-------------|
| `spawn(name, config)` | Start a named process |
| `kill(name)` | Kill by name |
| `killAll()` | Kill all |
| `restart(name, config?)` | Restart with optional new config |
| `listProcesses()` | List running processes |
| `getStatus(name)` | Get process status |
| `writeStdin(name, data)` | Write raw string to stdin |
| `detectRuntimes()` | Detect bun/node/deno availability |
| `setRuntimePath(rt, path)` | Set custom executable path |
| `getRuntimePaths()` | Get custom path overrides |

| Event | Payload |
|-------|---------|
| `js-process-stdout` | `{ name: string, data: string }` |
| `js-process-stderr` | `{ name: string, data: string }` |
| `js-process-exit` | `{ name: string, code: number \| null }` |

---

## Approach B: Building from Scratch

When you need full control or a different architecture (e.g., single shared process instead of named processes, Tauri event relay instead of direct stdio, or SvelteKit/other frameworks).

### Step 1: Rust — spawn and relay

Add tokio to `src-tauri/Cargo.toml`:
```toml
[dependencies]
tokio = { version = "1", features = ["process", "io-util", "sync", "rt"] }
```

Core Rust pattern in `src-tauri/src/lib.rs`:
```rust
use std::sync::Arc;
use tauri::{async_runtime, AppHandle, Emitter, Listener, Manager};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::process::{Child, ChildStdin, Command};
use tokio::sync::Mutex;

struct ProcessState {
    child: Child,
    stdin: ChildStdin,
}

struct AppState {
    process: Arc<Mutex<Option<ProcessState>>>,
}

fn spawn_runtime(app: &AppHandle) -> Result<ProcessState, String> {
    let mut cmd = Command::new("bun");
    cmd.args(["src/backend/main.ts"]);
    cmd.stdin(std::process::Stdio::piped());
    cmd.stdout(std::process::Stdio::piped());
    cmd.stderr(std::process::Stdio::piped());

    let mut child = cmd.spawn().map_err(|e| e.to_string())?;
    let stdin = child.stdin.take().ok_or("no stdin")?;
    let stdout = child.stdout.take().ok_or("no stdout")?;
    let stderr = child.stderr.take().ok_or("no stderr")?;

    // Relay stdout to all frontend windows via Tauri events
    let handle = app.clone();
    async_runtime::spawn(async move {
        let reader = BufReader::new(stdout);
        let mut lines = reader.lines();
        while let Ok(Some(line)) = lines.next_line().await {
            let _ = handle.emit("runtime-stdout", &line);
        }
    });

    // Relay stderr
    let handle2 = app.clone();
    async_runtime::spawn(async move {
        let reader = BufReader::new(stderr);
        let mut lines = reader.lines();
        while let Ok(Some(line)) = lines.next_line().await {
            eprintln!("[runtime stderr] {}", line);
            let _ = handle2.emit("runtime-stderr", &line);
        }
    });

    Ok(ProcessState { child, stdin })
}
```

Listen for frontend-to-runtime messages:
```rust
// In .setup() closure:
app.listen("frontend-to-runtime", move |event| {
    let payload = event.payload().to_string();
    let state = state_clone.clone();
    async_runtime::spawn(async move {
        let mut guard = state.lock().await;
        if let Some(ref mut proc) = *guard {
            let msg: String = serde_json::from_str(&payload).unwrap_or(payload);
            let mut to_write = msg;
            if !to_write.ends_with('\n') {
                to_write.push('\n');
            }
            let _ = proc.stdin.write_all(to_write.as_bytes()).await;
            let _ = proc.stdin.flush().await;
        }
    });
});
```

### Step 2: Frontend IO adapter

Bridge Tauri events to kkrpc's IoInterface:
```typescript
import { emit, listen, type UnlistenFn } from "@tauri-apps/api/event";

export class TauriEventIo {
  name = "tauri-event-io";
  isDestroyed = false;
  private listeners: Set<(msg: string) => void> = new Set();
  private queue: string[] = [];
  private pendingReads: Array<(value: string | null) => void> = [];
  private unlisten: UnlistenFn | null = null;

  async initialize(): Promise<void> {
    this.unlisten = await listen<string>("runtime-stdout", (event) => {
      // CRITICAL: re-append \n that BufReader::lines() strips
      const message = event.payload + "\n";

      for (const listener of this.listeners) listener(message);

      if (this.pendingReads.length > 0) {
        this.pendingReads.shift()!(message);
      } else {
        this.queue.push(message);
      }
    });
  }

  async read(): Promise<string | null> {
    if (this.isDestroyed) return new Promise(() => {});  // hang, don't spin
    if (this.queue.length > 0) return this.queue.shift()!;
    return new Promise((resolve) => this.pendingReads.push(resolve));
  }

  async write(message: string): Promise<void> {
    await emit("frontend-to-runtime", message);
  }

  on(event: "message" | "error", listener: (msg: string) => void) {
    if (event === "message") this.listeners.add(listener);
  }

  off(event: "message" | "error", listener: Function) {
    if (event === "message") this.listeners.delete(listener as any);
  }

  destroy() {
    this.isDestroyed = true;
    this.unlisten?.();
    this.pendingReads.forEach((r) => r(null));
    this.pendingReads = [];
    this.queue = [];
    this.listeners.clear();
  }
}
```

### Step 3: Connect kkrpc

```typescript
import { RPCChannel } from "kkrpc/browser";
import type { BackendAPI } from "../backend/types";

const io = new TauriEventIo();
await io.initialize();

const channel = new RPCChannel<{}, BackendAPI>(io, { expose: {} });
const api = channel.getAPI() as BackendAPI;

// Type-safe calls
const result = await api.add(5, 3);
```

### Step 4: Clean shutdown

```rust
// In .build().run() callback:
.run(move |app_handle, event| {
    if let RunEvent::ExitRequested { .. } = &event {
        let state = app_handle.state::<AppState>();
        let proc = state.process.clone();
        async_runtime::block_on(async {
            let mut guard = proc.lock().await;
            if let Some(mut proc) = guard.take() {
                drop(proc.stdin);  // drop stdin first
                let _ = proc.child.kill().await;
                let _ = proc.child.wait().await;
            }
        });
    }
});
```

### Step 5: Capabilities for multi-window

```json
{
  "windows": ["main", "window-*"],
  "permissions": [
    "core:default",
    "core:event:default",
    "core:webview:allow-create-webview-window"
  ]
}
```

Note: `WebviewWindow` from `@tauri-apps/api/webviewWindow` requires `core:webview:allow-create-webview-window`, not `core:window:allow-create`.

---

## Critical Pitfalls

### 1. Newline framing
Rust's `BufReader::lines()` strips trailing `\n`. kkrpc (and all newline-delimited JSON protocols) need `\n` to delimit messages. **The frontend IO adapter MUST re-append `\n`** to every payload received from Tauri events.

### 2. kkrpc read loop spin
kkrpc's internal `listen()` loop continues on `null` reads — it only stops if the IO adapter has `isDestroyed === true`. If `read()` returns `null` without `isDestroyed` being set, the loop spins at 100% CPU. **Solution:** `read()` should return a never-resolving promise when destroyed, and expose `isDestroyed`.

### 3. Channel cleanup
Call `channel.destroy()` (not just `io.destroy()`) to properly reject pending RPC promises. The channel's destroy will call io.destroy internally.

### 4. Mutex contention in Rust
The Tauri event listener for stdin writes and the kill/restart commands both need the process mutex. **Take the process handle out of the lock scope before kill/wait.** Drop stdin first to unblock pending writes.

### 5. Tauri event serialization
Tauri events serialize payloads as JSON strings. When the Rust event listener receives a message to forward to stdin, it may need to deserialize the outer JSON string wrapper: `serde_json::from_str::<String>(&payload)`.

### 6. Vite pre-bundle cache
When using the plugin with `file:` dependency links, Vite caches the pre-bundled version. After rebuilding the plugin's guest-js, delete `node_modules/.vite` in the consuming app and run `pnpm install` to pick up new exports.

### 7. Deno imports
Deno workers must use `npm:kkrpc/deno` for the import specifier and `.ts` file extensions for local imports (e.g., `./shared-api.ts`).

### 8. `deno compile` and `node_modules`
`deno compile` will crash with a stack overflow if run from a directory that contains `node_modules` — Deno attempts to traverse and compile the entire directory tree. **Deno worker source must live in a separate directory** that is set up as its own Deno package with a `deno.json` declaring dependencies (e.g., kkrpc).

Example setup:
```
examples/
  deno-compile/           # Separate Deno package — no node_modules here
    deno.json             # { "imports": { "kkrpc/deno": "npm:kkrpc/deno" } }
    main.ts               # Deno worker source
    shared-api.ts         # Type definitions (copy from backends/)
  tauri-app/
    backends/             # Contains node_modules from npm
      deno-worker.ts      # Used for dev mode (deno run), NOT for deno compile
```

Run `deno install` in the deno package directory to cache dependencies before compiling. The build script should compile from the separate directory:
```bash
deno compile --allow-all --output src-tauri/binaries/deno-worker-$TARGET ../deno-compile/main.ts
```

### 9. Dev vs Prod mode
In dev mode, spawn runtimes directly (`bun script.ts`) or use compiled binaries via `config.sidecar` (see Step 7 above). In production, consider:
- **Compiled sidecar (recommended):** `bun build --compile` / `deno compile` produces a standalone binary — use `config.sidecar` to spawn it, and Tauri's `externalBin` to bundle it. No runtime needed on user machines.
- **Bundled JS scripts:** Worker scripts import `kkrpc` which needs `node_modules`. Bundle them first with `bun build --target bun/node` to inline dependencies, then add as Tauri resources via `bundle.resources`. Resolve at runtime with `resolveResource()` from `@tauri-apps/api/path`
- The Rust code checks for sidecar first, then falls back to bundled JS with system runtime

## Production Deployment

### Option 1: Compiled sidecar (no runtime needed on user machine)
```bash
TARGET=$(rustc -vV | grep host | cut -d' ' -f2)
bun build --compile src/backend/main.ts --outfile src-tauri/binaries/backend-$TARGET
```
Add to `tauri.conf.json`:
```json
{ "bundle": { "externalBin": ["binaries/backend"] } }
```
Spawn with:
```typescript
await spawn("backend", { sidecar: "backend" });
```

### Option 2: Bundled JS as resource (requires runtime on user machine)
Bundle the worker to inline dependencies (kkrpc):
```bash
bun build backends/worker.ts --target bun --outfile src-tauri/workers/worker.js
```
Add to `tauri.conf.json`:
```json
{ "bundle": { "resources": { "workers/worker.js": "workers/worker.js" } } }
```
Spawn with:
```typescript
import { resolveResource } from "@tauri-apps/api/path";
const script = await resolveResource("workers/worker.js");
await spawn("worker", { runtime: "bun", script });
```

## References

- [kkrpc](https://github.com/nicepkg/kkrpc) — cross-runtime RPC library
- [Tauri v2 Plugin Guide](https://tauri.app/develop/plugins/)
- [Tauri v2 Capabilities](https://tauri.app/security/capabilities/)