Skip to content

bun create defaults to no install (zero-install onboarding); node unchanged #682

Description

@vivek7405

Problem

The scaffold auto-runs an install at create time (packages/cli/lib/create.js ~L1399, runInstall), and in bun mode it forces bun install. After #675 a Bun app does NOT need an install to run: bun run dev / bun run start resolve deps on demand via the generated webjs-bun.mjs bootstrap. So bun create webjs (and --runtime bun) installs unnecessarily, contradicting the zero-install story. Node still needs the install to run, so Node keeps install-by-default.

Design / approach

Make the create-time install default PER RUNTIME: Node installs (current behavior), Bun skips (new). Both flags stay explicit overrides.

  • bin (packages/cli/bin/webjs.js, the create case ~L524): today const noInstall = rest.includes('--no-install') then passes install: !noInstall (true unless --no-install). Change to parse BOTH flags and pass a TRI-STATE: --install gives true, --no-install gives false, neither gives undefined (let scaffoldApp decide per runtime). Add --install to the create help text + flag list.
  • create.js (scaffoldApp, ~L243): today const shouldInstall = opts.install === true. Change to const shouldInstall = opts.install ?? !isBun so a Node app installs by default and a Bun app skips by default, while an explicit { install: true|false } / --install / --no-install still wins. isBun is resolved inside scaffoldApp (auto-detected from npm_config_user_agent OR --runtime bun), which is exactly why the default must live here, not in the bin (the bin does not know the auto-detected runtime).
  • Post-create message (create.js ~L1401): when Bun + skipped, print guidance instead of "Running 'bun install'", e.g. "Skipped install. Bun resolves deps on demand, so bun run dev / bun run start work as-is. Run bun install if you want editor type intelligence and a pinned bun.lock." Node path message unchanged.

Implementation notes (for the implementing agent)

  • Landmine: the bin passes install: !noInstall today (always true/false, never undefined), so flipping create.js alone is NOT enough. The bin MUST pass undefined when neither flag is given, or Bun keeps installing.
  • Do NOT change Node's default (Node needs node_modules to run; only Bun is zero-install via Zero-install dev/start on Bun via native auto-install (carve from #669) #675).
  • bun.lock is not committed when install is skipped (it is generated on the first bun install); that is fine for zero-install, note it in the message/docs.
  • Invariants: this is CLI scaffold behavior; respect invariant release: bump core/server/cli versions, honest engines fields #11 in any new prose/message, and the docs-site html template invariant feat(server): replace esbuild TS stripping with Node 24+ strip-types #9 in the page edits.
  • Tests + docs: test/scaffolds/scaffold-runtime.test.js already calls scaffoldApp with { install: false } (unaffected), but ADD assertions for the NEW default logic: with install omitted, a bun scaffold does not install and a node scaffold does (or assert the resolved shouldInstall via a seam if a real install is impractical in the test, e.g. assert the printed message / a spy). Update docs/app/docs/runtime/page.ts (Bun section + install-model note), docs/app/docs/getting-started/page.ts (the Bun pointer), agent-docs/runtime.md (zero-install section), and the scaffold packages/cli/templates/AGENTS.md "Running on Bun" section to state bun create is install-free by default with --install to opt in.
  • Builds on Zero-install dev/start on Bun via native auto-install (carve from #669) #675 (the zero-install bootstrap). cli is published, so this is a cli feat (a future release bump).

Acceptance criteria

  • bun create webjs my-app (and webjs create my-app --runtime bun) does NOT run an install by default; it prints zero-install guidance.
  • webjs create my-app (Node) still installs by default (unchanged).
  • --install forces an install on Bun; --no-install skips on Node; explicit flags win over the per-runtime default.
  • Scaffold tests assert the per-runtime default + the flag overrides.
  • Docs (runtime page, getting-started, agent-docs/runtime.md, scaffold AGENTS) state the Bun install-free default and --install opt-in.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

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