You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Runtime-specific guidance (Node 24+ vs Bun) is scattered across docs/app/docs/{getting-started,deployment,no-build,architecture}/page.ts and the AGENTS surfaces, and it drifts: the #675 zero-install detail already lives in two places. There is no single canonical page, and no obvious home for Deno or any future runtime.
Design / approach
Add a new docs-site topic page docs/app/docs/runtime/page.ts (nav label "Runtime") that is the SINGLE SOURCE OF TRUTH for runtime mechanics:
Intro: webjs runs on Node 24+ or Bun (Deno planned).
A comparison matrix (Node, Bun, Deno-planned) covering:
103 Early Hints: node-only (Bun.serve has no informational-response API).
Per-runtime "commands" + "under the hood" sections: the scaffold flag (webjs create --runtime node|bun; Bun auto-detected via bun create webjs, Add a Bun-first scaffold mode (--runtime bun) across all 3 templates #541), the exact run commands, and the install model including the zero-install-vs-pinned reproducibility tradeoff (dev resolve-on-demand vs an immutable prod image).
A "future runtimes" note: the runtime-neutral listener seam already exists (startServer selects the Bun.serve shell via a seam designed to also host Deno.serve / embedded adapters), so Deno slots in here when it lands. Mark Deno as planned, not yet supported.
Canonical-home rule (avoid the opposite drift): make /docs/runtime the one place runtime mechanics live, and TRIM the deep detail out of getting-started + deployment into brief one-liners that LINK to /docs/runtime. Do the trim in the SAME PR so there is no duplication.
Implementation notes (for the implementing agent)
Where to edit: new docs/app/docs/runtime/page.ts (model an existing topic page like docs/app/docs/deployment/page.ts: a default-exported function returning an html tagged template, plus metadata). Add the nav entry (locate the docs nav/sidebar config under docs/app/; check docs/app/docs/layout.ts and any nav constant; grep for existing topic slugs like getting-started / deployment to find the list). Trim docs/app/docs/getting-started/page.ts (the Bun-app paragraph) and docs/app/docs/deployment/page.ts (the --runtime bun bullet) to pointers to /docs/runtime.
Source content from AGENTS.md (the no-build + scaffold/runtime sections), agent-docs/advanced.md / agent-docs/configuration.md, and the existing scattered page mentions.
Tests + docs: boot-check the new page AND the two trimmed pages serve 200 (the in-repo docs app via createRequestHandler, prod mode); confirm the nav renders the new entry. Docs-only, no package code, so NO version bump.
Acceptance criteria
A single /docs/runtime page documents Node + Bun commands and differences with a comparison matrix and a future-Deno note.
getting-started + deployment LINK to /docs/runtime instead of duplicating the runtime detail (no duplicated zero-install explanation).
Problem
Runtime-specific guidance (Node 24+ vs Bun) is scattered across
docs/app/docs/{getting-started,deployment,no-build,architecture}/page.tsand the AGENTS surfaces, and it drifts: the #675 zero-install detail already lives in two places. There is no single canonical page, and no obvious home for Deno or any future runtime.Design / approach
Add a new docs-site topic page
docs/app/docs/runtime/page.ts(nav label "Runtime") that is the SINGLE SOURCE OF TRUTH for runtime mechanics:npm installthennpm run dev/start; Bun is zero-install (bun run dev/startroute through the generatedwebjs-bun.mjsbootstrap so Bun auto-install resolves deps on demand, Zero-install dev/start on Bun via native auto-install (carve from #669) #675).node:httpvs nativeBun.serve(about 1.9x req/s on the listening path, Pluggable server-listener seam + a Bun.serve backend #511).module.stripTypeScriptTypesvsamaroon Bun (Support both Bun and Node runtimes (first-class create + run) #508).node:sqlitevsbun:sqlite(both built-in; thebusy_timeout+ WAL pragma, feat: remove better-sqlite3, use native node:sqlite + bun:sqlite #670 / fix: set busy_timeout + WAL on the SQLite connection to stop "database is locked" #674).node --watchvsbun --hot(Dev hot-reload of server-side modules is stale on Bun (query cache-bust ignored) #514).wslibrary vs nativeBun.serve+ theBunWsAdapter(Pluggable server-listener seam + a Bun.serve backend #511).Bun.servehas no informational-response API).webjs create --runtime node|bun; Bun auto-detected viabun create webjs, Add a Bun-first scaffold mode (--runtime bun) across all 3 templates #541), the exact run commands, and the install model including the zero-install-vs-pinned reproducibility tradeoff (dev resolve-on-demand vs an immutable prod image).startServerselects theBun.serveshell via a seam designed to also hostDeno.serve/ embedded adapters), so Deno slots in here when it lands. Mark Deno as planned, not yet supported.Canonical-home rule (avoid the opposite drift): make
/docs/runtimethe one place runtime mechanics live, and TRIM the deep detail out of getting-started + deployment into brief one-liners that LINK to/docs/runtime. Do the trim in the SAME PR so there is no duplication.Implementation notes (for the implementing agent)
docs/app/docs/runtime/page.ts(model an existing topic page likedocs/app/docs/deployment/page.ts: a default-exported function returning anhtmltagged template, plusmetadata). Add the nav entry (locate the docs nav/sidebar config underdocs/app/; checkdocs/app/docs/layout.tsand any nav constant; grep for existing topic slugs likegetting-started/deploymentto find the list). Trimdocs/app/docs/getting-started/page.ts(the Bun-app paragraph) anddocs/app/docs/deployment/page.ts(the--runtime bunbullet) to pointers to/docs/runtime.AGENTS.md(the no-build + scaffold/runtime sections),agent-docs/advanced.md/agent-docs/configuration.md, and the existing scattered page mentions.htmltagged-template body, use<code>tags) and invariant release: bump core/server/cli versions, honest engines fields #11 (no em-dash, no space-surrounded hyphen or semicolon pause, no colon after a code-shaped LHS) in all prose.llms.txt/llms-full.txtregenerate live from the doc pages, so no manual edit. Keep Deno framed as planned (do not imply it works; see the deferred notes in AGENTS.md).createRequestHandler, prod mode); confirm the nav renders the new entry. Docs-only, no package code, so NO version bump.Acceptance criteria
/docs/runtimepage documents Node + Bun commands and differences with a comparison matrix and a future-Deno note./docs/runtimeinstead of duplicating the runtime detail (no duplicated zero-install explanation).