@webjsdev/cli 0.10.63 → 0.10.65

package/lib/create.js

@@ -974,9 +974,22 @@ import { Pool } from 'pg';
 import * as schema from './schema.server.ts';
 
 // The only file that opens the driver. Cached on globalThis across dev reloads.
+// The pool relies on no session state (no SET, no LISTEN, no advisory locks
+// held across queries), so it also works behind a transaction pooler. Idle
+// connections close after 10 s; a database that is down fails a request in
+// 5 s instead of hanging it; DATABASE_POOL_MAX caps the pool (default 10).
 const g = globalThis as unknown as { __webjs_db?: unknown };
 function open() {
-  return drizzle({ client: new Pool({ connectionString: process.env.DATABASE_URL }), relations: schema.relations });
+  const pool = new Pool({
+    connectionString: process.env.DATABASE_URL,
+    max: Number(process.env.DATABASE_POOL_MAX) || 10,
+    idleTimeoutMillis: 10_000,
+    connectionTimeoutMillis: 5_000,
+  });
+  // An idle connection the server drops (a restart, a failover) emits
+  // 'error' on the pool, and an unhandled one would crash the process.
+  pool.on('error', (err) => console.error('[db] idle connection lost:', err.message));
+  return drizzle({ client: pool, relations: schema.relations });
 }
 export const db = (g.__webjs_db ??= open()) as ReturnType<typeof open>;
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.63",
+  "version": "0.10.65",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.79",
+    "@webjsdev/server": "^0.8.81",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -128,6 +128,8 @@ A `redirectTo` that arrives from a request (a form field or a query param, for O
 
 For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
 
+**The header updates on its own after sign-in and sign-out.** A layout that reads `auth()` to render "Sign in" / "Sign out" is re-rendered after any mutating form submission the router handles (a form bound to a sign-in action, or a plain POST to `/api/auth/signin/credentials` / `/api/auth/signout`), and its markup is morphed in place, so there is nothing to refresh by hand (#1557). Only a sign-out done over RPC from a component (`await logout(); navigate('/')`) needs `await refreshPage('shell')` after it, since that navigation is a plain GET.
+
 Sessions are JWT by default (stateless, scales horizontally). OAuth
 providers handle the full redirect flow. Read the session anywhere on the
 server with `auth()`.

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -17,6 +17,8 @@ Read this when a task touches client navigation, prefetch, partial-page swaps, s
 
 The router auto-enables the moment `@webjsdev/core` loads in the browser, which is any page that ships a component. There is nothing to import or opt into. It intercepts same-origin `<a>` clicks (including inside shadow DOM), fetches the target HTML, and replaces only the inside of the deepest shared layout. Outer header, sidenav, and footer DOM is never re-rendered, so scroll positions, input values, and `<details>` state survive a navigation.
 
+**A mutating form submission re-renders the layouts (#1557).** A link click keeps the layout chrome by construction, but a form action can change what a layout renders: a sign-in sets the cookie the header reads, a sign-out clears it. So a POST / PUT / PATCH / DELETE form the router submits sends NO `X-Webjs-Have` (the redirect `fetch` follows keeps request headers, so a have-header would make the server short-circuit the very layouts that need to re-run), and the swap applies the boundary plan as usual and then MORPHS the chrome outside the plan's range, level by level from `<body>` down. The morph is keyed + positional and state-preserving, so a hydrated layout component survives unless its own markup changed, and form controls keep what the reader typed (a 422 re-render included). When the chain from `<body>` to the range cannot be paired safely (a different depth or tag, or a hydrated component wrapping `${children}`), it takes the full-body tier instead, which is correct and only loses component state. Nodes appended to `<body>` at runtime (a dev overlay, a dialog portal) trail the server-rendered content and are left alone. A frame-targeted submission keeps its frame-only swap, and an RPC mutation followed by `navigate()` is a GET navigation, so call `refreshPage('shell')` after it when the layout depends on what changed.
+
 **The nav parse must preserve comments.** SSR wraps each layout's children AND the page itself in a KEYED boundary comment pair (open `<!--wj:children:<segment>:<route-key>-->`, close `<!--/wj:children:<segment>-->`, #1015). The route-key is the region's resolved concrete path with each substituted param value percent-encoded (so a user-controlled value can never terminate the comment or collide with the `:` delimiter). The router STRICTLY scans both the live and incoming DOM into segment maps: a close must id-match its innermost open, and ANY truncation, mispair, duplicate, or legacy anonymous open poisons the whole scan. The swap decision is two-tier with Next.js remount parity: a CHANGED route-key REPLACES (a fresh remount, permanents regrafted) at the PARENT of the shallowest changed boundary (a layout's boundary wraps only its children, so its own param-derived markup lives in the parent's range; anchoring there remounts the layout chrome too, exactly like Next re-rendering the layout with new params), else MORPH (the keyed state-preserving reconcile) at the deepest shared boundary when it is the leaf on both sides. The X-Webjs-Have header carries `segment:route-key` entries so the server re-renders (and re-ships) a dynamic layout the client holds for other params instead of short-circuiting past it. A poisoned scan or no shared segment degrades to a FULL PAGE LOAD (dev logs the cause), never a guessed recovery, so silent DOM corruption is structurally impossible. Hydration keys off another comment (`<!--webjs-hydrate-->`, which `__isHydrating()` reads as a component's first child). So the router and hydration both ride on comments SURVIVING the parse that turns a navigation response into a Document, which makes that parse a load-bearing correctness boundary rather than an implementation detail.
 
 `Document.parseHTMLUnsafe` STRIPS every comment in Chromium 150 (#1007). No other parse API does: `DOMParser`, `setHTMLUnsafe`, `template.innerHTML`, and plain `innerHTML` all preserve them, and so does the document's own navigation parser, which is why a hard refresh always looked correct and only soft nav broke. With the boundaries gone the router degrades to a full page load (correct, just not soft); with `webjs-hydrate` gone a slotted light-DOM component misses the hydration adopt path. `parseHTML` therefore PROBES `parseHTMLUnsafe` once for losslessness instead of sniffing versions, uses it when it is lossless (it is the only single-pass API that also processes Declarative Shadow DOM), and otherwise parses with `DOMParser`, which preserves comments. A fixed browser silently returns to the fast path.

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -138,6 +138,30 @@ export async function generateMetadata(ctx: MetadataContext): Promise<Metadata>
 
 Common fields: `title` (string or `{ template, default, absolute }`), `description`, `keywords`, `metadataBase` (resolves relative URLs in `openGraph` / `twitter` / `alternates` / `icons`), `openGraph`, `twitter`, `robots`, `alternates.canonical`, `icons`, `manifest`, and `jsonLd` (schema.org structured data, single object or array, HTML-safe-escaped automatically). `viewport`, `themeColor`, and `colorScheme` may also be set via a split `export const viewport = { ... }`. `cacheControl` is emitted as a response HEADER (not a `<meta>`); pages default to `no-store`, and any other value enables conditional GET (a weak `ETag` + `304`), `private` included. See https://webjs.dev/docs for the full field list.
 
+### Search and share defaults (SEO)
+
+Set `SITE_URL` (the app's public origin, e.g. `https://shop.example.com`) in production. It is the default `metadataBase`, and with it every page gets, unless it sets its own:
+
+- `<link rel="canonical">` = site URL + the page's pathname (query dropped). Opt one page out with `alternates: { canonical: null }`. Without a site URL no canonical is emitted, because the request host can be set by a client.
+- `og:title` / `og:description` from `title` / `description`, `og:type` `website`, `og:url` = the canonical.
+- `og:image` from the nearest `opengraph-image` route above the page (and `twitter:image` from `twitter-image`), when the page declares no image.
+- `twitter:card`: `summary_large_image` when there is an image, else `summary`.
+
+`openGraph` and `twitter` take Next's shapes: `images` is a string, `URL`, `{ url, width, height, alt, type }` or an array of those (emits `og:image` + `og:image:width` / `height` / `alt`); camelCase keys become snake_case (`siteName` -> `og:site_name`); `publishedTime` / `modifiedTime` / `authors` / `section` / `tags` emit `article:*`. `metadataBase` may be a string or a `URL`.
+
+So a public page needs only a specific title and description:
+
+```ts
+export const metadata: Metadata = {
+  title: 'Opening hours',
+  description: 'When the bakery is open, including public holidays.',
+};
+```
+
+A signed-in or private page says `robots: { index: false }` (put it on the private section's layout and every page below inherits it); `pages()` then leaves it out of the sitemap too.
+
+Structured data goes in `jsonLd` (from `generateMetadata` when it depends on a record): one schema.org object or an array, escaped safely into `<script type="application/ld+json">`.
+
 ## Control-flow throws
 
 From `@webjsdev/core`: throw to short-circuit a page / layout render or a form-bound action.
@@ -225,7 +249,30 @@ The BOUNDARY FILE's own crash (it throws, or fails to import at all) is reported
 Two further consequences: a layout that fetches runs its fetch again on a boundary response, and a `<webjs-suspense>` inside a wrapped layout shows its fallback, because a boundary response is buffered so its status is final before the first byte. A 404 for a URL that matched NO route has no chain to wrap in and stays a bare document.
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). That verbatim document is exactly why it is the one boundary left UNWRAPPED: a second shell would nest inside the root layout's, wrapping it would re-run the code that just threw, and with no boot script it could not soft-swap anyway. `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
-Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
+Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments (a nested one answers under its segment: `app/blog/opengraph-image.ts` is `/blog/opengraph-image`) and default-export a possibly-async function that receives `{ request, url, siteUrl, pages }`. `siteUrl` is `SITE_URL`, else the request origin. `sitemap` may return an ARRAY of entries (urls may be paths, resolved against `siteUrl`) and `robots` an OBJECT (Next's `MetadataRoute.Robots` shape); the server serializes them. `sitemap()` / `sitemapIndex()` / `robots()` from `@webjsdev/server` are the same serializers, for a route that builds its own Response.
+
+`pages()` lists every public page as sitemap entries: each static page (route groups dropped), each dynamic page that exports `generateSitemapParams()`, and none whose static metadata chain says `robots: { index: false }`. So the sitemap follows the app as pages are added:
+
+```ts
+// app/sitemap.ts
+import type { MetadataRouteContext } from '@webjsdev/server';
+export default async function sitemap({ pages }: MetadataRouteContext) {
+  return pages();
+}
+
+// app/products/[id]/page.ts: list the products this route serves
+export async function generateSitemapParams() {
+  return (await listProducts()).map((p) => ({ params: { id: p.id }, lastModified: p.updatedAt }));
+}
+
+// app/robots.ts
+import type { MetadataRouteContext } from '@webjsdev/server';
+export default function robots({ siteUrl }: MetadataRouteContext) {
+  return { rules: { userAgent: '*', allow: '/', disallow: ['/account', '/api/'] }, sitemap: `${siteUrl}/sitemap.xml` };
+}
+```
+
+`generateSitemapParams()` returns params objects (`[{ id: '1' }]`) or entries carrying them (`[{ params: { id: '1' }, lastModified }]`).
 
 The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
 
@@ -248,7 +295,7 @@ export const metadata = {
 
 Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
 
-`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
+`opengraph-image` and `twitter-image` are LINKED too, Next's behaviour: a page that declares no `openGraph.images` gets `og:image` pointing at the nearest `opengraph-image` route above it (absolute against the site URL), and likewise `twitter:image`. A page that declares its own image keeps it.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
@@ -256,5 +303,5 @@ export default function OgImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">...</svg>`;
   return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
 }
-// app/page.ts  ->  export const metadata = { openGraph: { images: ['/opengraph-image'] } };
+// every page without its own image now carries og:image = <site>/opengraph-image
 ```

package/templates/.agents/skills/webjs/references/runtime.md

@@ -89,6 +89,10 @@ The scaffold ships a matching Dockerfile per runtime: a Node image for the defau
 
 Both `node:sqlite` and `bun:sqlite` default `busy_timeout` to 0, so a contended write throws `database is locked` immediately. The generated connection sets `PRAGMA busy_timeout = 5000` plus `PRAGMA journal_mode = WAL` on the raw client before Drizzle wraps it, on both runtime branches, so you get a sane 5-second wait instead of an instant failure. This is already wired in the scaffold's `db/connection.server.ts`.
 
+## Postgres pool (`--db postgres`)
+
+A `--db postgres` app opens one `pg` Pool in `db/connection.server.ts`. It holds no session state between queries (no `SET`, `LISTEN`, or advisory lock kept across them), so the same code works behind a transaction pooler. Idle connections close after 10 seconds, a connection attempt gives up after 5 seconds (a database that is down fails the request instead of hanging it), `DATABASE_POOL_MAX` caps the pool (default 10), and an idle connection the server drops (a restart or failover) is logged rather than crashing the process. Keep it that way: do not add `SET` statements or session-scoped features to app code.
+
 ## Verifying a runtime-sensitive change
 
 Most app code needs no runtime-specific testing, because it does not touch a runtime seam. If you DO change something runtime-sensitive (the serializer, a stream, `node:crypto`, low-level request handling, anything that behaves differently under `Bun.serve` versus `node:http`), prove it on both runtimes. The Node suite is the source of truth, and an additive Bun matrix re-runs the runtime-sensitive tests under Bun. See `testing.md` for the cross-runtime matrix and the `test/bun/**` assertions.

package/templates/gallery/app/opengraph-image.ts

@@ -1,9 +1,9 @@
 // app/opengraph-image.ts serves /opengraph-image (the preview card social
 // platforms show when the site is shared). The Open Graph spec wants 1200x630.
-// Returning a Response with an inline SVG keeps this buildless; for per-page
-// previews, read the request in a nested static segment's opengraph-image.ts
-// and compose the title in. Reference it from metadata via
-// `openGraph: { images: ['/opengraph-image'] }`.
+// Returning a Response with an inline SVG keeps this buildless. Every page that
+// declares no `openGraph.images` gets og:image pointing here automatically
+// (absolute against SITE_URL); a nested `app/<segment>/opengraph-image.ts`
+// covers the pages under that segment instead.
 export default function OpengraphImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
     <rect width="1200" height="630" fill="#1e2226"/>

package/templates/gallery/app/robots.ts

@@ -1,12 +1,16 @@
-// app/robots.ts serves /robots.txt. The default export returns a string (served
-// as text/plain) or an object. This example allows all crawlers and points them
-// at the sitemap. Tighten the rules (Disallow paths) for a real app.
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+// app/robots.ts serves /robots.txt. `robots()` from @webjsdev/server writes the
+// file from Next's robots object (returning the bare object works too; the
+// server runs it through the same helper). `siteUrl` is SITE_URL (your public
+// origin) when set, else the request origin, so the Sitemap line is always
+// absolute. Disallow signed-in areas and API paths, and mark those pages
+// `robots: { index: false }` too, so a crawler that follows a link still does
+// not index them.
+import { robots } from '@webjsdev/server';
+import type { MetadataRouteContext } from '@webjsdev/server';
 
-export default function Robots() {
-  return [
-    'User-agent: *',
-    'Allow: /',
-    `Sitemap: ${SITE_URL}/sitemap.xml`,
-  ].join('\n');
+export default function Robots({ siteUrl }: MetadataRouteContext) {
+  return robots({
+    rules: { userAgent: '*', allow: '/', disallow: ['/api/'] },
+    sitemap: [`${siteUrl}/sitemap.xml`, `${siteUrl}/sitemaps`],
+  });
 }

package/templates/gallery/app/sitemap.ts

@@ -1,19 +1,13 @@
-// app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
-// server function; `sitemap(entries)` from @webjsdev/server serializes a
-// spec-valid XML sitemap. In a real app, build the entries from your content
-// (a query over posts/products), so new content is discoverable without editing
-// this file. Here it lists the gallery's static routes as an example.
-import { sitemap } from '@webjsdev/server';
+// app/sitemap.ts serves /sitemap.xml. The route receives `{ pages, siteUrl, ... }`
+// and may return an ARRAY of entries, which the server serializes to spec-valid
+// XML. `pages()` lists every public page of the app: each static page, each
+// dynamic page that exports `generateSitemapParams()` (the params it serves,
+// usually from a query), and none whose metadata says `robots: { index: false }`.
+// So adding a page adds it here with no edit. URLs use SITE_URL (your public
+// origin) when it is set, else the request origin. Append data-driven entries
+// that are not pages (a feed, a file) to the array.
+import type { MetadataRouteContext } from '@webjsdev/server';
 
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
-
-export default function Sitemap() {
-  const routes = ['/', '/features/routing', '/features/boundaries'];
-  return sitemap(
-    routes.map((path) => ({
-      url: `${SITE_URL}${path}`,
-      changeFrequency: 'weekly' as const,
-      priority: path === '/' ? 1.0 : 0.7,
-    })),
-  );
+export default async function Sitemap({ pages }: MetadataRouteContext) {
+  return pages();
 }

package/templates/gallery/app/sitemaps/files/route.ts

@@ -0,0 +1,14 @@
+// A child sitemap built by hand with `sitemap(entries)`: for URLs that are not
+// pages (a feed, a downloadable file), which `pages()` in app/sitemap.ts cannot
+// know about. Each entry is { url, lastModified?, changeFrequency?, priority? };
+// the helper escapes every URL and drops a malformed entry instead of emitting
+// broken XML.
+import { sitemap } from '@webjsdev/server';
+
+export async function GET(req: Request) {
+  const site = (process.env.SITE_URL || new URL(req.url).origin).replace(/\/$/, '');
+  return new Response(
+    sitemap([{ url: `${site}/manifest.json`, changeFrequency: 'yearly', priority: 0.1 }]),
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } },
+  );
+}

package/templates/gallery/app/sitemaps/route.ts

@@ -1,16 +1,17 @@
 // A sitemap INDEX: for a large site split across several sitemaps, this points
 // crawlers at each child sitemap. `sitemapIndex(sitemaps)` (from @webjsdev/server)
-// serializes the spec-valid <sitemapindex> XML, the counterpart of `sitemap(entries)`
-// in app/sitemap.ts (the single-file case). A route.ts serves it at /sitemaps;
-// in a real app the children would be sharded (posts, products, ...).
+// serializes the spec-valid <sitemapindex> XML; `sitemap(entries)` serializes one
+// child. app/sitemap.ts (the pages) is one child; ./files/route.ts (URLs that are
+// not pages) is another. In a real app the children would be sharded (posts,
+// products, ...). Build absolute URLs from SITE_URL, your public origin.
 import { sitemapIndex } from '@webjsdev/server';
 
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
-
-export async function GET() {
+export async function GET(req: Request) {
+  const site = (process.env.SITE_URL || new URL(req.url).origin).replace(/\/$/, '');
   return new Response(
     sitemapIndex([
-      { url: `${SITE_URL}/sitemap.xml` },
+      { url: `${site}/sitemap.xml` },
+      { url: `${site}/sitemaps/files` },
     ]),
     { headers: { 'content-type': 'application/xml; charset=utf-8' } },
   );