@webjsdev/cli 0.10.15 → 0.10.17

package/bin/webjs.js

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
+import { planDevSupervisor } from '../lib/dev-supervisor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -39,7 +40,8 @@ if (cmd !== 'help' && cmd !== undefined) {
 const TEMPLATES = ['full-stack', 'api', 'saas'];
 
 const USAGE = `webjs commands:
-  webjs dev   [--port 8080]                       Start dev server with live reload
+  webjs dev   [--port 8080] [--no-hot]            Start dev server with live reload
+                                                  (--no-hot: run in-process, no hot-reload supervisor)
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
@@ -83,7 +85,8 @@ async function main() {
   }
   switch (cmd) {
     case 'dev': {
-      // If we're already inside the --watch child, start the server directly.
+      // If we're already inside the reload child (node --watch or bun --hot),
+      // start the server directly.
       if (process.env.__WEBJS_DEV_CHILD === '1') {
         const { startServer } = await import('@webjsdev/server');
         // Load `.env` BEFORE resolving the port so a `PORT` set there is in
@@ -104,36 +107,31 @@ async function main() {
       const hint = prismaDevHint(process.cwd());
       if (hint) console.error(hint);
 
-      // Otherwise, spawn ourselves as a child with node --watch.
-      // This restarts the process on file changes, guaranteeing a fresh
-      // Node ESM module cache. Without this, edits to transitively-imported
-      // modules (actions, queries, components, utils) don't take effect
-      // because Node caches ESM by URL with no public invalidation API.
-      // Build watch paths from directories that exist in the project.
+      // Decide how to run: in-process (`--no-hot`), or re-exec'd under the host
+      // runtime's hot-reload supervisor (`node --watch` on Node, `bun --hot` on
+      // Bun, #514). The branch logic lives in the pure `planDevSupervisor` so it
+      // is unit-testable without spawning a process.
       const { existsSync } = await import('node:fs');
-      const watchPaths = [];
-      for (const dir of ['app', 'components', 'modules', 'lib', 'actions']) {
-        if (existsSync(dir)) watchPaths.push('--watch-path', dir);
-      }
-      // Watch root middleware/config if present
-      for (const f of ['middleware.ts', 'middleware.js']) {
-        if (existsSync(f)) watchPaths.push('--watch-path', f);
+      const plan = planDevSupervisor({
+        isBun: !!process.versions.bun,
+        argv: process.argv.slice(1),
+        noHot: rest.includes('--no-hot'),
+        exists: (p) => existsSync(p),
+      });
+
+      if (plan.mode === 'inline') {
+        const { startServer } = await import('@webjsdev/server');
+        loadAppEnv(process.cwd());
+        const port = resolvePort(flag(rest, '--port'));
+        await startServer({ appDir: process.cwd(), port, dev: true });
+        break;
       }
 
-      const child = spawn(
-        process.execPath,
-        [
-          '--watch',
-          '--watch-preserve-output',
-          ...watchPaths,
-          ...process.argv.slice(1),
-        ],
-        {
-          stdio: 'inherit',
-          cwd: process.cwd(),
-          env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
-        },
-      );
+      const child = spawn(process.execPath, plan.args, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
+      });
       child.on('exit', (code) => process.exit(code ?? 0));
       break;
     }

package/lib/dev-supervisor.js

@@ -0,0 +1,61 @@
+/**
+ * Dev-server reload supervisor planning for `webjs dev` (issue #514).
+ *
+ * `webjs dev` re-execs itself under the host runtime's hot-reload supervisor so
+ * an edit to a transitively-imported module (an action, query, component, util)
+ * takes effect without a manual restart. Both runtimes cache ES modules by
+ * resolved URL with no public invalidation API, so the dev re-import in
+ * `@webjsdev/server`'s `dev.js` relies on the runtime's own file-watching cache
+ * invalidation:
+ *
+ * - **Node** has no in-place module-cache eviction, so it re-execs under
+ *   `node --watch`, which RESTARTS the process on a file change (a fresh ESM
+ *   cache each time). The dev re-import additionally appends a `?t=` cache-bust
+ *   query that Node honours between restarts.
+ * - **Bun** keys its module cache by path and IGNORES that `?t=` query, so the
+ *   `node --watch` model does not transfer: without help a re-imported module
+ *   stays STALE on Bun (the #514 bug). Bun's `--hot` invalidates loaded modules
+ *   on a file change WITHOUT restarting the process, which is exactly what the
+ *   dev re-import needs; `Bun.serve` is reused across hot reloads, so the
+ *   listener is not duplicated. `--hot` auto-watches every loaded file, so the
+ *   node `--watch-path` flags do not apply (and are not Bun flags).
+ *
+ * This pure planner returns the spawn decision so the bin stays a thin shell and
+ * the branch logic is unit-testable without spawning a process.
+ */
+
+/**
+ * Plan how `webjs dev` runs its server.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.isBun  Whether the host runtime is Bun (`process.versions.bun`).
+ * @param {string[]} opts.argv  `process.argv.slice(1)` (the script path followed by its args), forwarded to the child verbatim.
+ * @param {boolean} opts.noHot  Whether `--no-hot` was passed (opt out of the supervisor entirely).
+ * @param {(path: string) => boolean} opts.exists  Existence check for the Node `--watch-path` targets (relative to cwd). Unused on Bun.
+ * @returns {{ mode: 'inline' } | { mode: 'spawn', args: string[] }}
+ *   `inline` runs the server in this process (no reload watcher); `spawn`
+ *   re-execs `process.execPath` with `args` and `__WEBJS_DEV_CHILD=1`.
+ */
+export function planDevSupervisor({ isBun, argv, noHot, exists }) {
+  // `--no-hot` opts out of the reload supervisor on either runtime: run the dev
+  // server in THIS process with no watcher. Degraded dev (a deep-import edit
+  // needs a manual restart) but useful under an external process manager or a
+  // debugger that wants a single, un-re-exec'd process.
+  if (noHot) return { mode: 'inline' };
+
+  if (isBun) return { mode: 'spawn', args: ['--hot', ...argv] };
+
+  // Node: re-exec under `node --watch`, watching the project dirs/files that
+  // exist. `--watch-preserve-output` keeps prior logs across a restart.
+  const watchPaths = [];
+  for (const dir of ['app', 'components', 'modules', 'lib', 'actions']) {
+    if (exists(dir)) watchPaths.push('--watch-path', dir);
+  }
+  for (const f of ['middleware.ts', 'middleware.js']) {
+    if (exists(f)) watchPaths.push('--watch-path', f);
+  }
+  return {
+    mode: 'spawn',
+    args: ['--watch', '--watch-preserve-output', ...watchPaths, ...argv],
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.15",
+  "version": "0.10.17",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -96,7 +96,7 @@ self-review loop.
 ## Framework rules
 
 - No build step: ES modules served directly.
-- **Erasable TypeScript only.** Node 24+ strips types via
+- **Erasable TypeScript only.** The runtime (Node 24+ or Bun) strips types via
   `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position
   preservation, no sourcemap). The scaffold's `tsconfig.json` sets
   `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace`

package/templates/.cursorrules

@@ -102,7 +102,7 @@ self-review loop.
 ## Framework rules
 
 - No build step: source files are served as ES modules
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)

package/templates/.github/copilot-instructions.md

@@ -98,7 +98,7 @@ each change must include.
 
 - No build step: source files are served as ES modules. Don't introduce
   build tools or bundlers in the critical path.
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.

package/templates/AGENTS.md

@@ -393,6 +393,23 @@ In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
 start`) as the CMD over `node ... webjs.js start ...`. The npm form
 fires `prestart`; the direct binary form skips it.
 
+### Running on Bun instead of Node
+
+webjs runs on **Node 24+ or Bun**. The same `package.json` scripts work on
+either; to run under Bun, force it with `--bun` so the server executes on Bun
+rather than the `webjs` bin's Node shebang:
+
+```sh
+bun install
+bun --bun run dev      # or: bun --bun run start
+```
+
+On Node the `.ts` type-stripping is the built-in `module.stripTypeScriptTypes`;
+on Bun (which has no built-in) it comes from `amaro` automatically, so the same
+source serves identically. SSR action-result seeding (an internal hydration
+optimization) is off on Bun (it needs `module.registerHooks`), which only means
+an async-render component re-fetches once on hydration, no behavior change.
+
 **Containerized deploy ships with the scaffold.** `Dockerfile`,
 `compose.yaml`, and `.dockerignore` are scaffolded at the app root. The
 Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs
@@ -1126,10 +1143,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    browser-only). Never fetch initial data in `connectedCallback` /
    `firstUpdated`. Fetch in the page function (server) and pass it as
    a prop. See *Component pattern* above.
-8. **Erasable TypeScript only.** Node 24+ strips types via
-   `module.stripTypeScriptTypes` (whitespace replacement, byte-exact
-   line and column position preservation, no sourcemap shipped to the
-   browser). Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so
+8. **Erasable TypeScript only.** The runtime strips types at the runtime
+   layer (Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro`
+   on Bun, which is byte-identical), with whitespace replacement so
+   line and column positions are byte-exact and no sourcemap ships to
+   the browser. Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so
    the TS compiler rejects: `enum`, `namespace` with values,
    constructor parameter properties, legacy decorators with
    `emitDecoratorMetadata`, and `import = require`. Use the erasable

package/templates/CONVENTIONS.md

@@ -1054,7 +1054,7 @@ export async function createPost(input: {
 
 <!-- OVERRIDE -->
 - TypeScript with explicit `.ts` extensions in imports
-- **Erasable TypeScript only.** The framework strips types via Node 24+'s built-in `module.stripTypeScriptTypes` (whitespace replacement, byte-exact line + column preservation, no sourcemap shipped). Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so the compiler rejects: `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Write the erasable equivalents:
+- **Erasable TypeScript only.** The runtime strips types at the runtime layer (Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun, byte-identical) with whitespace replacement, so line + column positions are byte-exact and no sourcemap ships. Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so the compiler rejects: `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Write the erasable equivalents:
   ```ts
   // Not allowed
   enum Color { Red, Green, Blue }

package/templates/Dockerfile

@@ -3,11 +3,14 @@
 # Works with a plain `docker build` / `docker compose up`, and is the same
 # artifact the webdeploy hosting tool (ubicloud + uncloud) builds and ships.
 #
-# webjs serves .ts directly via Node's built-in type-stripping, so there is
-# NO JavaScript build step. **Node 24+ is REQUIRED**: on older Node the runtime
-# falls back to esbuild, whose class-declaration transform breaks webjs's SSR
-# walker for multi-class component files. Do not lower this base image
-# below 24 (the same version the CI workflow and the framework pin).
+# webjs serves .ts directly by stripping types at the runtime layer, so there is
+# NO JavaScript build step (webjs is buildless end to end; there is no bundler or
+# esbuild fallback). This image runs the app on **Node 24+**, where the strip is
+# the built-in `module.stripTypeScriptTypes`. webjs ALSO runs on **Bun** (where
+# the strip comes from `amaro` automatically), so you can swap this base for an
+# `oven/bun` image and start the app with `bun --bun run start`. Do not lower the
+# Node base below 24 (the floor the CI workflow and the framework pin enforce),
+# since the built-in stripper and recursive fs.watch need it.
 #
 # Security headers are set by the framework, not the proxy. webjs emits
 # X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and