How-to guides
Run on Node (dev:node)
Develop the product app outside workerd with KTB_DEV_NODE=1.
The default dev server runs the app on Cloudflare's workerd runtime (via Alchemy/Vite). For faster iteration or debugging Node-specific issues, run it on plain Node instead.
Run
cd apps/web
bun run dev:node # KTB_DEV_NODE=1 vp dev --port 3000The app is served at http://localhost:3000 either way — dev:node only
changes the runtime underneath.
When to use it
- Quicker startup and debugging when the failure is in app code, not the Workers runtime.
- Testing code paths that behave differently under Node vs workerd.
Caveats
- Bindings that only exist on Cloudflare (D1, R2, KV) have local
equivalents under
apps/web/src/lib/node-*.ts— SQLite via@ktb/db-sqlite, filesystem audio bucket, and a SQLite-backed queue (data/queue.db) that survives restarts. dev:secrets(cuora run) is still needed for secrets-backed features.- Anything runtime-specific (streams,
node:sqlitevs D1 client) should be verified on both runtimes before shipping.
Verify
bun run dev:nodeboots without workerd errors.- The feature you're touching works identically under
bun run dev.