@webjsdev/cli 0.10.28 → 0.10.30

package/bin/webjs.js

@@ -147,6 +147,12 @@ async function main() {
       // down on exit so a watcher cannot outlive the server.
       const { readAppTasks } = await import('../lib/app-tasks.js');
       const devTasks = readAppTasks(process.cwd());
+      // Load `.env` BEFORE the before-steps (same as `start`, L188), so a
+      // `dev.before` `webjs db migrate` sees DATABASE_URL from `.env`. Without
+      // this a Postgres dev migrate runs with no connection string and fails
+      // (sqlite survives via its `?? 'db/dev.db'` config fallback). The watch
+      // child / inline server load `.env` again later (idempotent).
+      loadAppEnv(process.cwd());
       await runPhaseBeforeSteps('dev', devTasks.dev.before, process.cwd());
       const killTasks = await startDevParallelTasks(devTasks.dev.parallel, process.cwd());
       process.on('SIGINT', () => { killTasks(); process.exit(0); });

package/lib/create.js

@@ -314,9 +314,9 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     },
     scripts: {
       // No `predev` / `prestart` hooks (#550): the `webjs` block below holds
-      // the start orchestration (`webjs db migrate`), run INSIDE `webjs start`,
-      // so `npm run start` (a thin alias) behaves identically. Drizzle has no
-      // codegen, so there is no dev `before` step.
+      // the dev + start orchestration (`webjs db migrate`), run INSIDE `webjs
+      // dev` / `webjs start`, so `npm run dev` / `start` (thin aliases) behave
+      // identically. Both apply pending migrations before serving (#725).
       //
       // Bun runtime (#541): the long-running server scripts (`dev` / `start`)
       // are prefixed `bun --bun` so the app SERVES on Bun. The `--bun` overrides
@@ -386,16 +386,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // into components/ui/ (they import @webjsdev/core, not the kit), and the
       // CLI resolves @webjsdev/ui from its own install.
     },
-    // Start task orchestration (#550). `webjs start` reads `start.before` and
-    // runs it in-process, so `npm run start` (a thin alias above) behaves
-    // identically. Drizzle has no codegen, so there is no dev `before` step;
-    // production applies pending migrations via `webjs db migrate`. The scaffold
+    // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
+    // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
+    // above) behave identically. Both apply pending migrations via `webjs db
+    // migrate` (idempotent, a no-op when the db is current), so a freshly
+    // generated migration is applied without a manual step (#725). The scaffold
     // uses the Tailwind browser runtime (no CSS build step), so there is no dev
     // `parallel` watcher here; an app that adds the Tailwind CLI puts its
     // `--watch` command under `webjs.dev.parallel`.
     webjs: {
-      // Drizzle has no codegen, so there is no dev `before` step. Production
-      // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
+      dev: { before: ['webjs db migrate'] },
       start: { before: ['webjs db migrate'] },
     },
   }, null, 2) + '\n');
@@ -667,6 +667,7 @@ function tune<T extends { exec(sql: string): unknown }>(client: T): T {
 
 async function open() {
   if ((globalThis as { Bun?: unknown }).Bun) {
+    // @ts-expect-error bun:sqlite is a Bun builtin with no Node typings
     const { Database } = await import('bun:sqlite');
     const { drizzle } = await import('drizzle-orm/bun-sqlite');
     return drizzle({ client: tune(new Database(url)), relations: schema.relations });
@@ -1388,13 +1389,22 @@ For AI agents, read this before editing scaffolded files:
   // Single copy-paste line so the user can move from "scaffold done"
   // to "dev server up" in one command. The full-stack and saas
   // templates ship with @webjsdev/ui already initialised; the api
-  // template has no UI but may add one later. Saas needs a one-time
-  // generate + migrate before the first run (the example User model wants
-  // its table to exist). Drizzle splits Prisma's `migrate dev` into
-  // `db:generate` (schema to SQL) then `db:migrate` (apply).
+  // template has no UI but may add one later.
   const installSegment = installed ? '' : `${pm} install && `;
-  const dbSegment = isSaas ? `${pm} run db:generate && ${pm} run db:migrate && ` : '';
+  // The saas example queries the users table on its first request (auth), so it
+  // needs a migration authored first: `db:generate` writes it and the
+  // `webjs.dev.before` migrate applies it on `run dev` (Drizzle splits Prisma's
+  // `migrate dev` into generate-then-migrate). The full-stack / api examples do
+  // not query the db on first paint, so they boot with just `run dev`; once you
+  // add a db route, `db:generate` then `run dev` is the loop (dev auto-migrates).
+  const dbSegment = isSaas ? `${pm} run db:generate && ` : '';
   const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
+  // Postgres needs a reachable DATABASE_URL before any migrate (sqlite uses a
+  // local file with no .env). Point it at a running database; `dev` / `start`
+  // then apply pending migrations via webjs.*.before.
+  const pgNote = dialect === 'postgres'
+    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\n`
+    : '';
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare
   // `webjs` npm name is owned by an unrelated package; `npx webjs
   // <cmd>` would fetch THAT package instead of ours when run outside
@@ -1410,7 +1420,7 @@ For AI agents, read this before editing scaffolded files:
 Next steps:
   ${runCommand}
   # → http://localhost:8080
-
+${pgNote}
 Optional:
   ${uiNote}
 `);

package/lib/saas-template.js

@@ -186,9 +186,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
   //     ALWAYS once the app modules import: auth() only reads a cookie, no DB
   //     query. This is the headline security assertion and it is REAL.
   //   The signup, login, and protected-route flow writes + reads a user, so it
-  //   needs the DB migrated (`npm run db:generate` then `npm run db:migrate`).
-  //   Until the users table exists those flows error, so the suite skips with a
-  //   clear message instead of crashing. After DB setup it runs for real.
+  //   needs the migrated users table (`npm run db:generate`, then `npm run dev`
+  //   applies it via webjs.dev.before). Until then those flows error, so the
+  //   suite probes readiness and skips with a clear message instead of crashing,
+  //   then runs for real once the db is set up.
   await mkdir(join(appDir, 'test', 'auth'), { recursive: true });
   // The generated comments reference `npm run db:*` setup; bun-ify them so a
   // bun-flavored saas app reads `bun run db:*` (#541; db is Node tooling, so a
@@ -205,12 +206,11 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');",
     "",
     "// The auth pages + dashboard middleware query the users table via Drizzle.",
-    "// Until `npm run db:generate` + `npm run db:migrate` have created it, a",
-    "// request hitting those modules 500s. We detect that at the RESPONSE level",
+    "// Until `npm run db:generate` has authored the migration (then `npm run dev`",
+    "// applies it via webjs.dev.before, or `npm run db:migrate` directly), a",
+    "// request hitting those modules 500s; we detect that at the RESPONSE level",
     "// (a 5xx on the dashboard) and SKIP with a clear message rather than report",
-    "// a misleading failure. After you run",
-    "//   npm install && npm run db:generate && npm run db:migrate",
-    "// every assertion below runs for real.",
+    "// a misleading failure. After the db is set up every assertion runs for real.",
     "process.env.DATABASE_URL ||= 'file:./dev.db';",
     "process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';",
     "",

package/package.json

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

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

@@ -145,7 +145,9 @@ self-review loop.
   a `.server.{js,ts}` file; the framework rewrites that import into an RPC
   stub for the browser. `lib/` holds both server-only infra
   (the DB in `db/*.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
-  `cn`); follow the same rule per file.
+  `cn`); follow the same rule per file. A TYPE-ONLY `import type { Todo } from
+  '#db/schema.server.ts'` is the exception, fine in a page or component because
+  the stripper erases it before it reaches the browser.
 - Keep pages and layouts as pure carriers so their modules stay out of the
   network tab. A page/layout never hydrates; the framework drops its module
   from the browser as long as its only browser job is registering the

package/templates/.cursorrules

@@ -114,7 +114,7 @@ self-review loop.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
+- Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.

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

@@ -110,7 +110,7 @@ each change must include.
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `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. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
-- Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'

package/templates/AGENTS.md

@@ -329,7 +329,7 @@ db/
   columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
   connection.server.ts   opens the driver, exports the \`db\` singleton (import \`db\` from here)
   seed.server.ts         optional seed (run via \`webjs db seed\`)
-  dev.db                 SQLite file (gitignored); run \`npm run db:migrate\` to create
+  dev.db                 SQLite file (gitignored); created when migrations apply (\`dev\`/\`start\` run \`webjs db migrate\`)
   migrations/            generated migration SQL (committed)
 drizzle.config.ts        drizzle-kit config (root; SQLite by default, --db postgres to switch)
 public/                  static assets, served at /public/*
@@ -387,13 +387,16 @@ lives in the `webjs` block of `package.json` and runs INSIDE
 
 ```jsonc
 "webjs": {
+  "dev": { "before": ["webjs db migrate"] },
   "start": { "before": ["webjs db migrate"] }
 }
 ```
 
-Drizzle has no codegen, so there is no dev `before` step. An app that
-adds the Tailwind CLI puts its `--watch` command under
-`webjs.dev.parallel` and it runs alongside the server, torn down on exit.
+Both `dev` and `start` apply pending migrations via `webjs db migrate`
+(idempotent, a no-op when the db is current), so a freshly generated
+migration is applied without a manual step. An app that adds the Tailwind
+CLI puts its `--watch` command under `webjs.dev.parallel` and it runs
+alongside the server, torn down on exit.
 `before` steps run to completion first; a failed `webjs db migrate`
 aborts the boot with a clear message rather than serving a stale schema.
 
@@ -457,7 +460,7 @@ Scripts (all wrap `drizzle-kit`):
 - `npm run db:push`: `webjs db push` (push the schema straight to the dev DB)
 - `npm run db:studio`: `webjs db studio` (visual DB browser)
 - `npm run db:seed`: `webjs db seed` (run `db/seed.server.ts`)
-- `webjs.start.before` runs `webjs db migrate` inside `webjs start` (idempotent; replaces the old `prestart` hook). No dev `before` step (no codegen).
+- `webjs.dev.before` and `webjs.start.before` both run `webjs db migrate` inside `webjs dev` / `webjs start` (idempotent; replaces the old `prestart` hook), so after you `db:generate` a migration it is applied on the next boot with no manual `db:migrate` step.
 
 Always import `db` from `db/connection.server.ts` (the globalThis-cached
 singleton avoids opening a new connection on every dev-server reload), and
@@ -1163,7 +1166,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    `lib/utils/cn.ts` with `cn`, design-
    system helpers). Server-only `lib/*` files must only be imported
    from `.server.ts`/`route.ts`/`middleware.ts`; browser-safe `lib/*`
-   files (like `lib/utils/cn.ts`) can be imported anywhere.
+   files (like `lib/utils/cn.ts`) can be imported anywhere. A TYPE-ONLY
+   import is the exception: `import type { Todo } from
+   '#db/schema.server.ts'` is fine in a page or component, because the
+   TypeScript stripper erases it before it reaches the browser, so
+   sharing a derived row type is safe and is not flagged.
 3. Event / property / boolean holes in `` html`` `` are unquoted:
    `@click=${fn}`, not `@click="${fn}"`.
 4. Component state lives in signals. Import `signal` from

package/templates/CONVENTIONS.md

@@ -268,11 +268,12 @@ docs". That is the agent's default behavior in a webjs project.
 
 Every webjs app uses **Drizzle + SQLite** for persistence by default. The
 scaffold ships the `db/` folder (`schema.server.ts`, `columns.server.ts`,
-`connection.server.ts`), the `webjs.start.before` step that runs
-`webjs db migrate` inside `webjs start` (#550), and the
+`connection.server.ts`), the `webjs.dev.before` + `webjs.start.before` steps
+that run `webjs db migrate` inside `webjs dev` / `webjs start` (#550), and the
 `npm run db:generate` / `db:migrate` / `db:push` / `db:studio` / `db:seed`
-scripts (which route through `webjs db` to drizzle-kit). Drizzle has no
-codegen, so there is no dev `before` step.
+scripts (which route through `webjs db` to drizzle-kit). The loop after a
+schema change is `db:generate` (authors the migration) then `webjs dev` (the
+`dev.before` step applies it); `db:generate` is never auto-run on boot.
 
 **AI agents: these rules are absolute.**
 
@@ -400,7 +401,7 @@ modules/
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - Components must call `Class.register('tag')`
-- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
+- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files." A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
 - **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 - **Keep pages and layouts as pure carriers, so their modules stay out of the network tab.** A page/layout never hydrates; the framework drops its module from the browser as long as its only browser-relevant job is registering the components it imports. It starts shipping its own module (invisible in tests) the moment its closure does any OTHER client work. So do not give a page/layout module-scope client work (a top-level call, a `window` / `document` / `customElements` access, a bare side-effect import, or a `@webjsdev/core/client-router` import: routing is automatic), and do not import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the browser's network tab.

package/templates/test/hello/browser/hello.test.js

@@ -51,11 +51,17 @@ suite('Example browser tests', () => {
     await assertNoA11yViolations(el);
   });
 
-  // Replace with your component tests:
-  // test('my-widget renders correctly', async () => {
-  //   await import('../../components/my-widget.ts');
-  //   const el = await ssrFixture(html`<my-widget></my-widget>`);
-  //   assert.ok(el.shadowRoot ?? el.firstElementChild);
-  //   await assertNoA11yViolations(el);   // opt-in a11y check
+  // Your REAL `.ts` app components load here. `webjs test --browser` serves
+  // them through the webjs dev pipeline (TypeScript stripped, any `.server.ts`
+  // action import rewritten to an RPC stub, `#` aliases resolved), so a
+  // component that talks to the server works in a real browser, not just a
+  // node test. Point the import at a component your app actually has:
+  //
+  // test('todo-list adds a row optimistically', async () => {
+  //   await import('../../../components/todo-list.ts');  // imports create-todo.server.ts
+  //   const el = await ssrFixture(html`<todo-list></todo-list>`);
+  //   el.querySelector('button')?.click();               // fires the action RPC
+  //   // assert on the DOM, then optionally:
+  //   await assertNoA11yViolations(el);
   // });
 });

package/templates/test/hello/e2e/hello.test.ts

@@ -1,12 +1,14 @@
-/**
- * Example E2E test: replace with tests for your user flows.
- *
- * Run:  WEBJS_E2E=1 webjs test
- * Or:   WEBJS_E2E=1 node --test test/**/e2e/**/*.test.ts
- *
- * Requires: puppeteer-core + chromium installed.
- *   npm i -D puppeteer-core
- */
+// Example E2E test: replace with tests for your user flows.
+//
+// Run:  WEBJS_E2E=1 webjs test
+//       (or point node --test at your e2e test files directly)
+//
+// Requires: puppeteer-core + chromium installed.
+//   npm i -D puppeteer-core
+//
+// Note: this header uses line comments on purpose. A JSDoc block comment
+// here cannot contain a glob like test/**/e2e/ because the ** followed by /
+// closes the block comment early and breaks TypeScript stripping.
 import { test, describe, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';

package/templates/test/hello/hello.test.ts

@@ -1,9 +1,7 @@
-/**
- * Example unit test: replace with tests for your modules.
- *
- * Run:  webjs test
- * Or:   node --test test/**/*.test.ts
- */
+// Example unit test: replace with tests for your modules.
+//
+// Run:  webjs test
+// Or:   node --test 'test/**/*.test.ts'
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { html } from '@webjsdev/core';

package/templates/web-test-runner.config.js

@@ -1,12 +1,8 @@
 /**
  * Web Test Runner configuration.
  *
- * Runs browser tests (components, directives, interactions) in real
- * Chromium via Playwright. Server tests (actions, queries) use node:test.
- *
- * Tests are organised by feature. Each feature folder may have a
- * `browser/` subfolder containing real-browser tests; the glob below
- * picks them up wherever they live.
+ * Runs browser tests (components, directives, interactions) in real Chromium
+ * via Playwright. Server tests (actions, queries) use node:test.
  *
  *   test/<feature>/<file>.test.ts             ← node tests
  *   test/<feature>/browser/<file>.test.js     ← this runner
@@ -15,15 +11,94 @@
  *   webjs test              # runs both server + browser tests
  *   webjs test --browser    # browser tests only
  *   webjs test --server     # server tests only
+ *
+ * A webjs browser test imports the REAL app: a `.ts` component that imports a
+ * `'use server'` action. Plain web-test-runner serves raw TypeScript with no
+ * transform, so that never loads. This config proxies every module request to
+ * the webjs dev pipeline via `createBrowserTestHandler`, so the browser gets
+ * the SAME output as `webjs dev`: TypeScript stripped, a `.server.ts` import
+ * rewritten to a typed RPC stub, `#`-alias imports resolved, `@webjsdev/core`
+ * served, and the importmap injected. (#806)
  */
 import { playwrightLauncher } from '@web/test-runner-playwright';
+import { createBrowserTestHandler } from '@webjsdev/server/testing';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+
+// One webjs handler for the app, warmed once and shared. Top-level await so the
+// importmap is ready before `testRunnerHtml` is called for the first test file.
+const webjs = await createBrowserTestHandler(resolve('.'));
 
 export default {
+  // Browser tests are `.js` (web-test-runner serves them through its own test
+  // framework); the components + modules they import are `.ts`, served
+  // transformed by the webjs middleware below.
   files: ['test/**/browser/**/*.test.js'],
-  nodeResolve: true,
-  browsers: [
-    playwrightLauncher({ product: 'chromium' }),
+  // webjs's importmap resolves `@webjsdev/core`, the `#` app aliases, and
+  // vendors, so web-test-runner must NOT rewrite bare specifiers to
+  // node_modules paths.
+  nodeResolve: false,
+  // Inject the webjs importmap so a bare / `#`-aliased import in a served module
+  // resolves in the browser exactly as it does under `webjs dev`.
+  testRunnerHtml: (testFrameworkImport) =>
+    `<!DOCTYPE html>
+<html>
+  <head>${webjs.importmapHtml()}</head>
+  <body>
+    <script type="module" src="${testFrameworkImport}"></script>
+  </body>
+</html>`,
+  middleware: [
+    async (ctx, next) => {
+      // web-test-runner owns: its own internals (/__web-test-runner,
+      // /__web-dev-server, /__wds), the TEST FILES themselves (it wraps each
+      // for the test framework), and the DOCUMENT navigation (the test-runner
+      // HTML page, `Sec-Fetch-Dest: document`). If webjs served the page, WTR's
+      // test bootstrap would never load and the session would time out. NOTE:
+      // match the WTR/WDS prefixes specifically, NOT a broad `/__web`, because
+      // webjs's own paths are `/__webjs/...` and MUST be proxied below.
+      if (
+        ctx.path.startsWith('/__web-test-runner') ||
+        ctx.path.startsWith('/__web-dev-server') ||
+        ctx.path.startsWith('/__wds') ||
+        /\.test\.(js|mjs)$/.test(ctx.path) ||
+        (ctx.get('sec-fetch-dest') || '') === 'document'
+      ) {
+        return next();
+      }
+      // The dev live-reload SSE has no meaning in a test run; short-circuit it
+      // so it neither hangs nor logs a 404.
+      if (ctx.path === '/__webjs/events') {
+        ctx.status = 204;
+        return;
+      }
+      // Everything else (a `.ts` component, a `.server.ts` action, the `#`
+      // alias, `/__webjs/core/*`, vendors) goes through the webjs dev pipeline.
+      // A GET/HEAD has no body; a POST (a browser test firing an action RPC)
+      // carries one. `ctx.req` is a Node IncomingMessage, so wrap it in a web
+      // ReadableStream (the same `Readable.toWeb` the server's own request
+      // bridge uses), NOT pass the raw Node stream.
+      const hasBody = ctx.method !== 'GET' && ctx.method !== 'HEAD';
+      const req = new Request(`http://localhost${ctx.originalUrl || ctx.url}`, {
+        method: ctx.method,
+        headers: ctx.headers,
+        body: hasBody ? Readable.toWeb(ctx.req) : undefined,
+        duplex: 'half',
+      });
+      const res = await webjs.handle(req);
+      // A 404 means webjs does not own this path; let web-test-runner try.
+      if (res.status === 404) return next();
+      ctx.status = res.status;
+      // Copy headers, but handle Set-Cookie separately: `Headers.forEach`
+      // comma-joins multiple Set-Cookie into one malformed value, so use
+      // `getSetCookie()` and append each (an action driving a multi-cookie auth
+      // flow would otherwise lose a cookie in the browser).
+      res.headers.forEach((value, key) => { if (key.toLowerCase() !== 'set-cookie') ctx.set(key, value); });
+      for (const cookie of res.headers.getSetCookie?.() ?? []) ctx.append('set-cookie', cookie);
+      ctx.body = Buffer.from(await res.arrayBuffer());
+    },
   ],
+  browsers: [playwrightLauncher({ product: 'chromium' })],
   testFramework: {
     config: {
       ui: 'tdd',