|
|
History
|
|
|---|---|---|
| .. | ||
| public | ||
| src | ||
| .env.example | ||
| .gitignore | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
ts-code-mode-web
TanStack AI Code Mode web example using React and TanStack Start.
Setup
Prerequisites
- Node.js >=18
- pnpm@10.17.0
- Xcode Command Line Tools (macOS)
Installation
pnpm install
Rebuilding isolated-vm (native module)
@tanstack/ai-isolate-node depends on isolated-vm, a native Node.js addon that must be compiled from source when a prebuilt binary is not available for your Node.js version.
When is this needed?
The isolated-vm package ships prebuilt binaries for select Node.js ABI versions. If you are running a newer Node.js version whose ABI is not yet included (e.g. Node.js 25.x / ABI 141), you will see an error like:
Error: No native build was found for platform=darwin arch=arm64 runtime=node abi=141 ...
loaded from: .../isolated-vm
How to fix it
-
Ensure Xcode Command Line Tools are installed (macOS):
xcode-select --install -
Run
node-gypvianpxinside theisolated-vmpackage directory (from the monorepo root):ISOLATED_VM_DIR="node_modules/.pnpm/isolated-vm@6.1.0/node_modules/isolated-vm" cd "$ISOLATED_VM_DIR" && npx node-gyp rebuildOr as a one-liner from the monorepo root (
/Users/jherr/tanstack/ai/code-mode):cd node_modules/.pnpm/isolated-vm@6.1.0/node_modules/isolated-vm && npx node-gyp rebuild -
A successful build ends with
gyp info okand producesbuild/Release/isolated_vm.node.
Notes
- Linker warnings about macOS version mismatches (
building for macOS-11.0, but linking with dylib ... built for newer version) are harmless and can be ignored. - The compiled
.nodefile lives in the pnpm content-addressable store and will need to be rebuilt afterpnpm install --forceor after upgrading Node.js to a different ABI version. - Python 3 is required by
node-gyp. It is detected automatically from$PATH.
Node.js 25 + isolated-vm runtime crash (SIGSEGV)
Even after successfully compiling from source, isolated-vm@6.1.0 crashes the server process (exit code 139, SIGSEGV) when run under Node.js 25.x. This is a V8 API incompatibility — Node 25 ships V8 14.1 whose internal C++ API has changed in ways that break isolated-vm's isolate creation code at runtime.
Symptom: The server dies silently with no JavaScript error or log output when the first code mode request is made.
Fix applied: All server routes in this example have been switched from the node isolate driver to the quickjs driver (@tanstack/ai-isolate-quickjs), which is a pure-JS sandbox with no native addon dependency and works on any Node.js version.
When isolated-vm works again: Once isolated-vm publishes a release compatible with Node 25 / V8 14.1, switch the driver back to 'node' in src/lib/create-isolate-driver.ts (default) and in each API route file. The node driver provides stronger isolation (true V8 process boundary) and is preferred in production.
Development
# Node (default) — Node isolate / QuickJS WASM / Cloudflare drivers
pnpm dev # http://localhost:3001
# Bun — native QuickJS via bun:ffi (@tanstack/ai-isolate-quickjs-bun)
pnpm dev:bun
# equivalent:
# CODE_MODE_BUN=1 bun --bun vite dev --port 3001
Bun mode (CODE_MODE_BUN=1)
When set (or when the process is Bun), this example:
- Defaults the isolate VM to
quickjs-bun(sidebar + server routes that callcreateIsolateDriver()) - Uses Nitro
preset: 'bun'for the server build - Keeps client
resolve.conditionswithoutbun(required so TanStack Router hydrates — see router-coreisServerdual package)
Optional overrides:
| Env | Effect |
|---|---|
CODE_MODE_BUN=1 |
Bun defaults + Nitro bun preset (also set by pnpm dev:bun) |
CODE_MODE_DEFAULT_VM=node|quickjs|quickjs-bun|cloudflare |
Force default isolate regardless of Bun |
Build
pnpm build
# Bun production build + run
pnpm build:bun
pnpm start:bun