Skip to content

docs: add a Runtime page consolidating Node + Bun (+ future Deno) differences #679

Description

@vivek7405

Problem

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:

  1. Intro: webjs runs on Node 24+ or Bun (Deno planned).
  2. A comparison matrix (Node, Bun, Deno-planned) covering:
  3. 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).
  4. 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.
  • Landmines: invariant feat(server): replace esbuild TS stripping with Node 24+ strip-types #9 (NO backtick inside an html tagged-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.txt regenerate 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).
  • 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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions