Shipping Next.js standalone inside a Tauri v2 sidecar (with 8 AI agents building it)

[nmelo]

We built Beadbox, a native desktop GUI for the beads issue tracker. The entire app runs on Next.js 16 with App Router, server components, server actions, and a WebSocket server for real-time updates.

Instead of rewriting the backend in Rust, we bundled the Node.js runtime as a Tauri v2 sidecar. Rust spawns node server.js (Next.js standalone output) and node ws-server.js at startup, finds free ports, and points the WebView at localhost. The web app doesn't know it's inside a native wrapper.

What we learned shipping Next.js standalone inside Tauri:

• NEXT_PUBLIC_ env vars are baked at build time. Our WS port is assigned dynamically by Rust at runtime, but the client bundle was compiled with whatever port we used at build. If they don't match, real-time updates silently break. We hardcode the port now.
• macOS GUI apps have a near-empty PATH (/usr/bin:/bin:/usr/sbin:/sbin). If your Next.js app shells out to anything installed via Homebrew, it won't find it. We spawn the user's login shell at startup to capture the real PATH.
• Zombie processes on force-quit: Node children survive if you don't handle cleanup. We use process groups + killpg on Unix, Job Objects on Windows.
• Bundle is ~160MB (84MB is Node.js). A bare Electron app starts around 200MB, so we come out ahead while keeping native window chrome and the system WebView.

The fun part: We're building Beadbox with 8 AI coding agents working simultaneously, all coordinated through beads itself. The agents claim issues, write code, push commits, and hand off to QA agents for verification. The issue tracker is tracking its own development in real-time.

Install: brew tap beadbox/cask && brew install --cask beadbox
Website: beadbox.app

Happy to answer questions about the sidecar pattern or multi-agent development workflow.