@webjsdev/cli 0.10.33 → 0.10.35

package/lib/create.js

@@ -542,9 +542,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // Environment variables
     '.env.example',
     // Project-level gitignore (node_modules, .webjs, .env, OS junk).
-    // The SQLite dev.db rule is appended programmatically below so it
-    // only appears for the sqlite dialect.
-    '.gitignore',
+    // Shipped as `gitignore` (no dot) and renamed to `.gitignore` on copy:
+    // npm STRIPS a `.gitignore` from a published tarball, so a dotfile name
+    // would arrive missing and the app would ship without a `.env` ignore
+    // (dogfood #845). The SQLite dev.db rule is appended programmatically
+    // below so it only appears for the sqlite dialect.
+    'gitignore',
     // Git hooks (blocks commits on main)
     '.hooks/pre-commit',
     // Claude Code config + hooks
@@ -617,14 +620,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   for (const f of templateFiles) {
     const src = join(TEMPLATES, f);
     if (existsSync(src)) {
-      await mkdir(dirname(join(appDir, f)), { recursive: true });
+      // `gitignore` ships without a dot (npm strips a published `.gitignore`)
+      // and is written to `.gitignore` in the generated app.
+      const dest = f === 'gitignore' ? '.gitignore' : f;
+      await mkdir(dirname(join(appDir, dest)), { recursive: true });
       let content = await readFile(src, 'utf8');
       content = content.replace(/\{\{APP_NAME\}\}/g, name);
       if (isBun) {
         if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
         else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
       }
-      await writeFile(join(appDir, f), content);
+      await writeFile(join(appDir, dest), content);
     }
   }
 
@@ -837,7 +843,9 @@ export default defineConfig({
       const cur = await readFile(gitignore, 'utf8');
       if (!cur.includes('db/dev.db')) await writeFile(gitignore, cur + gitignoreExtra);
     } else {
-      await writeFile(gitignore, 'node_modules\n.webjs\n' + gitignoreExtra);
+      // Defense in depth: if the template gitignore is ever absent, still
+      // never leave a real `.env` trackable (dogfood #845).
+      await writeFile(gitignore, 'node_modules\n.webjs\n.env\n.env.*\n!.env.example\n' + gitignoreExtra);
     }
   }
 
@@ -1093,6 +1101,15 @@ export default function RootLayout({ children }: { children: unknown }) {
   const nonce = cspNonce();
   return html\`
     <script nonce="\${nonce}">
+      // ===== OPTIONAL: light/dark theme apparatus (remove as one unit) =====
+      // This IIFE reads the saved or OS theme and toggles the data-theme
+      // attribute plus the dark class the ui kit reads, so the token VALUES in
+      // the root, dark, and data-theme style blocks below switch. It is what
+      // makes the app theme-aware. Building a SINGLE-theme app of your own?
+      // Delete this IIFE, delete the dark and light style blocks below, and set
+      // your palette once on the root selector. That removes the wiring so it
+      // cannot fight your own colours (it will not override a plain root
+      // palette). The header-measure IIFE that follows is unrelated, keep it.
       (function(){
         try {
           var mq = window.matchMedia('(prefers-color-scheme: light)');
@@ -1112,6 +1129,7 @@ export default function RootLayout({ children }: { children: unknown }) {
           mq.addEventListener('change', apply);
         } catch (_) {}
       })();
+      // ===== end optional theme apparatus =====
       // The header is position:fixed (not sticky): a sticky header flickers on
       // iOS WebKit during a client-router nav. fixed leaves normal flow, so
       // --header-h reserves its height for the content below. Measured here so

package/package.json

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

package/templates/AGENTS.md

@@ -351,7 +351,11 @@ app/                     ROUTING ONLY: thin route adapters (import from modules/
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
-  not-found.ts           custom 404 page
+  not-found.ts           custom 404 page (nearest wins on notFound())
+  forbidden.ts           403 page (nearest wins on forbidden())
+  unauthorized.ts        401 page (nearest wins on unauthorized())
+  global-error.ts        root-only app-wide error boundary (owns its <html>)
+  global-not-found.ts    root-only 404 for an unmatched-anywhere URL
   middleware.ts          global request middleware
   [slug]/page.ts         dynamic route segment
   [...rest]/page.ts      catch-all
@@ -392,6 +396,8 @@ test/<feature>/                feature-scoped tests, one folder per concern
   e2e/<name>.test.ts            end-to-end test (full app boot, opt in via WEBJS_E2E=1)
   smoke/<name>.test.ts          fast post-deploy sanity check
 middleware.ts            root middleware (optional, outermost)
+instrumentation.ts       optional boot hook: register() runs once; wire APM via setOnError
+instrumentation-client.ts  optional client boot hook, runs first before app modules
 ```
 
 ### The gallery (reference content, prune it)

package/templates/CONVENTIONS.md

@@ -495,11 +495,17 @@ Routes live under `app/` and follow NextJs App Router conventions:
 - `app/**/layout.ts`: Layout wrapper
 - `app/**/error.ts`: Error boundary
 - `app/**/middleware.ts`: Per-segment middleware
+- `instrumentation.ts` (app root): optional boot hook. `register()` runs once at startup; call `setOnError()` (from `@webjsdev/server`) inside it to wire an APM error sink (composes with `createRequestHandler({ onError })`).
+- `instrumentation-client.ts` (app root): optional client boot hook, imported first in the browser boot so it runs before app modules.
 
 **Special route files:**
 - `app/**/error.ts`: Error boundary. Default export receives `{ error }`, returns `TemplateResult`. Nearest boundary catches errors from pages below it.
 - `app/**/loading.ts`: Loading state. Auto-wraps the sibling page in a `Suspense` boundary. Shown while async page functions resolve.
 - `app/**/not-found.ts`: 404 page. Nearest wins when `notFound()` is thrown.
+- `app/**/forbidden.ts`: 403 page. Nearest wins when `forbidden()` is thrown (an authenticated user who lacks permission).
+- `app/**/unauthorized.ts`: 401 page. Nearest wins when `unauthorized()` is thrown (a request that is not authenticated).
+- `app/global-error.ts` (root only): app-wide error boundary, tried after nested `error.ts` boundaries. Renders its OWN `<!doctype><html><body>` document.
+- `app/global-not-found.ts` (root only): 404 for a URL that matches nothing anywhere.
 - `app/sitemap.ts`: Dynamic sitemap at `/sitemap.xml`. Export a function returning an array of `{ url, lastModified }`.
 - `app/robots.ts`: Dynamic robots.txt at `/robots.txt`.
 - `app/manifest.ts`: Web app manifest at `/manifest.json`.
@@ -928,7 +934,11 @@ global light-DOM namespace.
 
 Every page wraps its output in `<div class="page-<route>">`. Every
 layout wraps in `<div class="layout-<name>">`. Components scope via
-their tag. Styles colocate as `const STYLES = css\`…\`` + `<style>${'$'}{STYLES.text}</style>`.
+their tag. In a PAGE or LAYOUT (which render server-only and never
+hydrate) styles colocate as `const STYLES = css\`…\`` + `<style>${'$'}{STYLES.text}</style>`.
+In a COMPONENT, do NOT interpolate into `<style>` (the client drops the
+raw-text hole on hydrate, so the styles vanish); use `static styles =
+css\`…\`` or Tailwind classes instead.
 
 ```ts
 // app/dashboard/page.ts

package/templates/gallery/app/features/routing/[id]/page.ts

@@ -2,6 +2,10 @@
 // (possibly async) function receiving { params, searchParams, url }; it runs
 // ONLY on the server. Throw notFound() / redirect() to short-circuit.
 //
+// params / searchParams are BOTH synchronously readable AND awaitable: read
+// `params.id` directly, or `const { id } = await params` (the Next 15/16
+// pattern, supported so that muscle memory transfers). Either form is correct.
+//
 // Type-safe routes: instead of hand-typing `{ params: { id: string } }`, type
 // the props with PageProps<'<route>'>. `webjs types` (run automatically by
 // `webjs dev`) generates .webjs/routes.d.ts with a Route union and per-route
@@ -11,14 +15,18 @@
 import { html } from '@webjsdev/core';
 import type { PageProps } from '@webjsdev/core';
 
-export default function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
+export default async function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
+  // The Next-style await also works; `params.id` sync would be identical.
+  const { id } = await params;
   return html`
     <h1 class="text-h2 font-bold mb-4">Route param</h1>
-    <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
+    <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
     <p class="text-muted-foreground text-sm mt-3">
       Typed with <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>,
       so <code class="font-mono">params.id</code> is a checked
       <code class="font-mono">string</code> from the generated route union.
+      <code class="font-mono">params</code> is awaitable too:
+      <code class="font-mono">const { id } = await params</code> works, same value.
     </p>
     <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
   `;

package/templates/gitignore

@@ -0,0 +1,68 @@
+# deps
+node_modules/
+
+# webjs / framework caches.
+# `.webjs/routes.d.ts` (the generated route-types overlay, regenerated per
+# machine by `webjs types` / `webjs dev`) is correctly ignored by `**/.webjs/*`.
+# `.webjs/vendor/` is the EXCEPTION: it holds the committed importmap
+# manifest (.webjs/vendor/importmap.json) and optionally the vendored
+# bundle files (after `webjs vendor pin --download`). Both ship to
+# production via source control so the server doesn't need
+# api.jspm.io reachable at boot. Pattern is `**/.webjs/*` ignored,
+# `.webjs/vendor/` un-ignored, mirroring Rails' config/importmap.rb
+# + vendor/javascript/ being committed.
+#
+# DO NOT "simplify" the three lines below to `.webjs/`. Git's
+# gitignore semantics excludes the parent first; once the parent is
+# excluded, no `!**/.webjs/vendor/` negation can ever re-include children
+# (the failure is silent: `webjs vendor pin` runs, writes files, and
+# git ignores them with no warning). The `gitignore-vendor-not-ignored`
+# lint rule (run via `webjs check`) verifies this with
+# `git check-ignore` and will fail CI if the pattern regresses.
+#
+# The `**/` prefix matches `.webjs/` at ANY depth, not just this app's
+# root. A slash-bearing `.webjs/*` anchors to this file's directory, so
+# an app nested below its repo root (a monorepo package) would leak its
+# generated `.webjs/routes.d.ts` into `git status`. `**/.webjs/*` covers
+# the nested case while the negations still re-include vendor at each
+# depth (a re-included parent dir permits a child negation).
+**/.webjs/*
+!**/.webjs/vendor/
+!**/.webjs/vendor/**
+
+# generated Tailwind CSS, built from public/input.css via npm run dev / start
+public/tailwind.css
+
+# env (.env.example stays tracked; the real .env never is)
+.env
+.env.*
+!.env.example
+
+# logs
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# editors
+# `.vscode/*` ignored, but `.vscode/settings.json` (the webjs-config JSON
+# Schema association, #259) is committed so the editor validates package.json's
+# webjs block out of the box. Same gitignore shape as `.webjs/*` above: a bare
+# `.vscode/` would exclude the directory and no negation could re-include a
+# child, so the settings file would silently never ship.
+.vscode/*
+!.vscode/settings.json
+.idea/
+
+# test artifacts
+coverage/
+
+# AI assistants: local session state, scheduled-task locks, etc.
+# Repo-shared config (settings.json + hooks scripts) stays tracked so
+# every contributor and agent gets the same PreToolUse rules.
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+!.claude/hooks/**