@webjsdev/cli 0.10.5 → 0.10.6

package/bin/webjs.js

@@ -42,6 +42,7 @@ const USAGE = `webjs commands:
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check                                     Run correctness checks on the app
+  webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs create <name> [--template full-stack|api|saas] [--no-install]  Scaffold a new webjs app
                                                   (only 3 templates exist. default: full-stack with Prisma+SQLite)
                                                   Auto-runs the detected package manager's install in the new dir
@@ -277,6 +278,27 @@ async function main() {
       }
       break;
     }
+    case 'types': {
+      // Generate `.webjs/routes.d.ts` from the app's `app/` routes (#258),
+      // narrowing the @webjsdev/core `Route` href union + per-route `params`.
+      // Opt-in codegen: the static types in @webjsdev/core work without it
+      // (un-generated apps see `Route = string`).
+      const { generateRouteTypes } = await import('@webjsdev/server');
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      const appDir = process.cwd();
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      const outFile = join(outDir, 'routes.d.ts');
+      await writeFile(outFile, text);
+      // Count the typed routes (each `WebjsRoutes` key is one route literal).
+      const count = (text.match(/^\s+".*": true;$/gm) || []).length;
+      console.log(
+        `webjs types: wrote .webjs/routes.d.ts (${count} route${count === 1 ? '' : 's'} typed). ` +
+        `Ensure tsconfig "include" lists ".webjs/routes.d.ts" so tsserver picks it up.`,
+      );
+      break;
+    }
     case 'create': {
       const name = rest[0];
       if (!name || name.startsWith('-')) {

package/lib/create.js

@@ -346,6 +346,22 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         { name: '@webjsdev/ts-plugin' },
       ],
     },
+    // `.webjs/routes.d.ts` is the OPT-IN generated route-types overlay (#258):
+    // run `webjs types` (or `webjs dev`, which emits it) to narrow the
+    // @webjsdev/core `Route` href union + per-route `params`. Listed in
+    // `include` so tsserver picks it up; it is gitignored (regenerated per
+    // machine), so a fresh clone runs `webjs dev` / `webjs types` to recreate
+    // it, and the static @webjsdev/core types work even when it is absent.
+    include: [
+      'app/**/*',
+      'components/**/*',
+      'modules/**/*',
+      'lib/**/*',
+      'middleware.js',
+      'middleware.ts',
+      '.webjs/routes.d.ts',
+    ],
+    exclude: ['node_modules', '.webjs/vendor', 'prisma/migrations'],
   }, null, 2) + '\n');
 
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
@@ -397,6 +413,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // to main, mirroring the webjs framework's own CI.
     '.github/workflows/ci.yml',
     '.editorconfig',
+    // VS Code: associate the published webjs-config JSON Schema with the
+    // package.json `webjs` block, so an unknown / typo'd key (#259) is
+    // flagged natively in the editor instead of silently dropped.
+    '.vscode/settings.json',
     // Production / deploy scaffolding. `docker compose up --build` runs
     // the app locally with the same Dockerfile production builds from.
     'Dockerfile',

package/package.json

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

package/templates/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["/package.json"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "webjs": {
+            "$ref": "./node_modules/@webjsdev/server/webjs-config.schema.json"
+          }
+        }
+      }
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -112,6 +112,15 @@ layered on top:
 See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
 for the full walkthrough.
 
+**Config validation in `package.json`.** The scaffold ships
+`.vscode/settings.json`, which associates the published webjs-config JSON
+Schema (`@webjsdev/server/webjs-config.schema.json`) with the `webjs` block
+of `package.json`. In VS Code an unknown / typo'd `webjs.*` key (`redirect`
+for `redirects`, say) is then flagged inline instead of silently dropped to
+the default. The same shape is typed by the `WebjsConfig` type from
+`@webjsdev/core` (`import type { WebjsConfig } from '@webjsdev/core'`) for a
+typed reference.
+
 ## UI components: Webjs UI (preinstalled)
 
 This scaffold ships with the standard Webjs UI component kit
@@ -267,6 +276,28 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### Typed page / layout / route-handler props
+
+Type page / layout / route-handler arguments with the exported helpers so a
+param typo is a compile-time error:
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  return html`<h1>${params.slug}</h1>`;   // params typed { slug: string }
+}
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+export async function GET(req: Request, ctx: RouteHandlerContext) { /* ctx.params */ }
+```
+
+Run `webjs types` once (and ensure `tsconfig.json` `include` lists
+`.webjs/routes.d.ts`, the scaffold already does) to generate the route union:
+`PageProps<'/blog/[slug]'>['params']` then narrows to `{ slug: string }` and
+`navigate()` only accepts real app routes. `webjs dev` regenerates the file on
+startup, so it stays current. Without it, `params` is `Record<string, string>`
+and `navigate()` accepts any string (non-breaking).
+
 ## Database (Prisma + SQLite by default)
 
 Every scaffold includes a Prisma setup pointed at a local SQLite file.
@@ -709,8 +740,13 @@ return html`
 ```
 
 The router's `closest('webjs-frame')` detection takes precedence over
-layout markers. Only the frame's content swaps. Use this sparingly -
-folder-based layouts handle 99% of cases.
+layout markers. Only the frame's content swaps. Use this sparingly,
+folder-based layouts handle 99% of cases. When a frame nav's response
+lacks the matching `<webjs-frame id>` (e.g. an auth redirect), the router
+fires a cancelable, bubbling `webjs:frame-missing` event (detail
+`{ frameId, url, document }`) and leaves the frame unchanged rather than
+silently swapping the whole page; call `preventDefault()` to take over
+the outcome (e.g. `location.assign(e.detail.url)`).
 
 ### 5. `loading.ts` for per-segment skeletons