create-daloy 0.38.1 → 0.38.3

package/README.md

@@ -22,7 +22,7 @@ bun  create daloy           my-api
 The CLI is interactive when arguments are missing. It will ask you for:
 
 - A project directory name (defaults to `my-daloy-app`)
-- A template (`node-basic`, `vercel-edge`, `cloudflare-worker`, `bun-basic`, or `deno-basic`)
+- A template (`node-basic`, `vercel`, `cloudflare-worker`, `bun-basic`, or `deno-basic`)
 - A package manager (`pnpm`, `npm`, `yarn`, or `bun`) — not asked for the
   `deno-basic` runtime template
 - Whether to install dependencies
@@ -50,7 +50,7 @@ pnpm create daloy@latest my-api \
 
 | Flag | Description |
 | --- | --- |
-| `--template <name>` | `node-basic` (default), `vercel-edge`, `cloudflare-worker`, `bun-basic`, or `deno-basic`. |
+| `--template <name>` | `node-basic` (default), `vercel`, `cloudflare-worker`, `bun-basic`, or `deno-basic`. (`vercel-edge` is a deprecated alias for `vercel`.) |
 | `--package-manager <pm>` | `pnpm` (default), `npm`, `yarn`, or `bun`. Ignored for `deno-basic`. |
 | `--list-templates` | Print available templates with descriptions. |
 | `--install` / `--no-install` | Install dependencies after scaffolding. Defaults to **Y** for npm/yarn/bun and **N** for pnpm so you can review the hardened `.npmrc` / `pnpm-workspace.yaml` and aren't blocked by the 24h `minimumReleaseAge` embargo on the first run. |
@@ -88,17 +88,20 @@ A minimal Cloudflare Worker bootstrap using `@daloyjs/core/cloudflare` with:
 - `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
 - A Zod-validated `/healthz` route and contract-first `/books/:id` route exposed via `toFetchHandler(app)`.
 
-### `vercel-edge`
+### `vercel`
 
-A Vercel Edge API bootstrap using `@daloyjs/core/vercel` with:
+A Vercel API bootstrap on the **Node.js runtime** (Vercel's recommended runtime
+for standalone functions, on Fluid Compute) using `@daloyjs/core/vercel` with:
 
 - `api/[...path].ts` catch-all routing so DaloyJS owns the API surface.
-- `export const config = { runtime: "edge" }` ready for Vercel Edge.
-- Node.js migration notes using Vercel's default `{ fetch }` export shape.
+- `export default toFetchHandler(app)` — the `{ fetch }` shape Vercel Node.js Functions expect (no `runtime` export needed; Node.js is the default).
+- Notes for opting into the Edge runtime (`export const runtime = "edge"` + `toWebHandler(app)`) if you specifically need it.
 - `vercel dev` / `vercel deploy` scripts.
-- `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
+- `secureHeaders` and `requestId` enabled by default, with smaller serverless-friendly body and timeout limits.
 - A health route and bookstore route mirroring the Node starter.
 
+> The previous template name `vercel-edge` still works as a deprecated alias for `vercel`.
+
 ### `bun-basic`
 
 A [Bun](https://bun.sh) runtime starter using `@daloyjs/core/bun` with:
@@ -260,7 +263,7 @@ not need.
 - Zero runtime dependencies (uses only Node built-ins) for a clean supply-chain footprint.
 - A modern terminal experience with Unicode/color capability detection and ASCII fallbacks.
 - Templates are copied verbatim from this package's `templates/` directory.
-- Files and folders prefixed with `_` are renamed on copy (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_github/` → `.github`, `_agents/` → `.agents/`, `_Dockerfile` → `Dockerfile`, `_dockerignore` → `.dockerignore`, `_env.example` → `.env.example`) to survive npm packing.
+- Files and folders prefixed with `_` are renamed on copy (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_github/` → `.github`, `_agents/` → `.agents/`, `_vscode/` → `.vscode/`, `_Dockerfile` → `Dockerfile`, `_dockerignore` → `.dockerignore`, `_env.example` → `.env.example`) to survive npm packing.
 - pnpm-specific `.npmrc` hardening is kept only when you choose `pnpm`; other package managers get a clean project without unsupported config warnings.
 - pnpm projects ship with `ignore-scripts=true`, `minimum-release-age=1440`, `verify-store-integrity=true`, `prefer-frozen-lockfile=true`, and `strict-peer-dependencies=true` by default.
 - `--with-ci` projects ship with pinned GitHub Actions workflows, CODEOWNERS, Dependabot, SECURITY.md, and lockfile-source verification.
@@ -274,3 +277,5 @@ Every scaffolded project ships with two files that help AI coding agents (Copilo
 - `.agents/skills/daloyjs-best-practices/SKILL.md` — comprehensive operational guidance following the open `agents/skills/<skill-name>/SKILL.md` convention: when to use the skill, project structure, core workflows (adding routes, regenerating the OpenAPI spec and client), schema and validation conventions, error-handling patterns, middleware order, testing best practices (happy and unhappy paths), security best practices, logging and observability notes, configuration and secrets handling, deployment notes, pitfalls and guardrails, and process expectations.
 
 Both files are tailored to the chosen template (Node, Bun, Deno, Vercel Edge, or Cloudflare Workers), and Node-style templates rewrite their commands to match your selected package manager. They follow the "instruction budget" advice — small root file, progressive disclosure for the rest — so they don't waste agent tokens. Edit or delete them freely; the framework does not depend on them at runtime.
+
+Every scaffold also ships a `.vscode/mcp.json` (authored as `_vscode/mcp.json` in the template) that wires VS Code and other MCP-aware editors to the DaloyJS documentation MCP server (`https://daloyjs.dev/mcp`) over HTTP. AI assistants in your editor can then pull current DaloyJS docs with no manual setup. Delete the file or remove the server entry to opt out; it is editor configuration only and the framework does not depend on it at runtime.

package/bin/create-daloy.mjs

@@ -23,9 +23,9 @@ const TEMPLATE_OPTIONS = [
     description: "Traditional REST API with secure defaults and Hey API codegen",
   },
   {
-    value: "vercel-edge",
-    title: "Vercel Edge",
-    description: "Catch-all Vercel Edge route with Node.js migration notes",
+    value: "vercel",
+    title: "Vercel",
+    description: "Catch-all Vercel Functions REST API on the Node.js runtime (Fluid Compute)",
   },
   {
     value: "cloudflare-worker",
@@ -54,6 +54,15 @@ const PACKAGE_MANAGER_OPTIONS = [
 const TEMPLATES = TEMPLATE_OPTIONS.map((option) => option.value);
 const PACKAGE_MANAGERS = PACKAGE_MANAGER_OPTIONS.map((option) => option.value);
 
+// Deprecated template names kept as aliases so existing
+// `--template <old>` commands (and published docs/blog posts) keep working.
+// Each maps to its current canonical template value.
+const TEMPLATE_ALIASES = new Map([
+  // `vercel-edge` shipped before Vercel deprecated standalone Edge Functions;
+  // the template now targets the recommended Node.js runtime as `vercel`.
+  ["vercel-edge", "vercel"],
+]);
+
 const RENAME_ON_COPY = new Map([
   ["_gitignore", ".gitignore"],
   ["_npmrc", ".npmrc"],
@@ -65,6 +74,11 @@ const RENAME_ON_COPY = new Map([
   // `.agents/skills/<skill-name>/SKILL.md`. Templates author this as
   // `_agents/` so npm pack does not drop the dotfolder during publish.
   ["_agents", ".agents"],
+  // Directory: holds editor configuration such as `mcp.json`, which wires
+  // VS Code (and compatible editors) to the DaloyJS docs MCP server.
+  // Templates author this as `_vscode/` so npm pack does not drop the
+  // dotfolder during publish.
+  ["_vscode", ".vscode"],
 ]);
 
 // Templates that target a runtime instead of an npm package manager.
@@ -972,7 +986,7 @@ function cloudflareDeploySteps(packageManager) {
 }
 
 function renderDeployConfig({ template, packageManager, needsBunRuntime }) {
-  if (template === "vercel-edge") {
+  if (template === "vercel") {
     return {
       header: vercelDeployHeader(),
       jobName: "Deploy to Vercel",
@@ -1669,6 +1683,12 @@ async function main() {
     if (!template) {
       template = rl ? await askChoice(rl, "Choose a starter template:", TEMPLATE_OPTIONS, "node-basic") : "node-basic";
     }
+    // Resolve deprecated template aliases (e.g. `vercel-edge` -> `vercel`).
+    if (TEMPLATE_ALIASES.has(template)) {
+      const canonical = TEMPLATE_ALIASES.get(template);
+      logWarn(`Template "${template}" is deprecated; using "${canonical}" instead.`);
+      template = canonical;
+    }
     if (!TEMPLATES.includes(template)) {
       logError(`Unknown template "${template}". Available: ${TEMPLATES.join(", ")}`);
       process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.38.1",
+  "version": "0.38.3",
   "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
   "type": "module",
   "license": "MIT",

package/sbom.cdx.json

@@ -1,25 +1,25 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:5874d6d1-4f7c-5889-b1dc-59abaf86bc40",
+  "serialNumber": "urn:uuid:2a24975c-f4c4-542d-80c9-be6056ddc994",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-11T09:54:26.989Z",
+    "timestamp": "2026-06-16T19:48:12.143Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.38.1"
+        "version": "0.38.3"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@0.38.1",
+      "bom-ref": "pkg:npm/create-daloy@0.38.3",
       "name": "create-daloy",
-      "version": "0.38.1",
+      "version": "0.38.3",
       "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
-      "purl": "pkg:npm/create-daloy@0.38.1",
+      "purl": "pkg:npm/create-daloy@0.38.3",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-0.38.1",
+        "tagId": "swidtag-create-daloy-0.38.3",
         "name": "create-daloy",
-        "version": "0.38.1",
+        "version": "0.38.3",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@0.38.1",
+      "ref": "pkg:npm/create-daloy@0.38.3",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-0.38.1",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.1-5874d6d1-4f7c-5889-b1dc-59abaf86bc40",
+  "name": "create-daloy-0.38.3",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.3-2a24975c-f4c4-542d-80c9-be6056ddc994",
   "creationInfo": {
-    "created": "2026-06-11T09:54:26.989Z",
+    "created": "2026-06-16T19:48:12.143Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "0.38.1",
+      "versionInfo": "0.38.3",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/create-daloy@0.38.1"
+          "referenceLocator": "pkg:npm/create-daloy@0.38.3"
         }
       ]
     }

package/templates/bun-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/bun-basic/package.json

@@ -17,7 +17,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.1",
+    "@daloyjs/core": "^0.38.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/bun-basic/src/build-app.ts

@@ -18,6 +18,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(process.env.TRUST_PROXY_HOPS
+      ? { behindProxy: { hops: Number(process.env.TRUST_PROXY_HOPS) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -27,7 +40,15 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${process.env.PORT ?? 3000}` }],
+      // Leave `servers` unset so the Scalar "Try it" panel and the generated
+      // client target the origin the docs are served from — the deployed
+      // domain in production, localhost in dev — which keeps "Try it" within
+      // the connect-src 'self' CSP on every platform. Never hardcode a URL
+      // here: a localhost default breaks "Try it" once deployed. Set PUBLIC_URL
+      // to pin an absolute base URL (e.g. for client codegen).
+      ...(process.env.PUBLIC_URL
+        ? { servers: [{ url: process.env.PUBLIC_URL }] }
+        : {}),
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/bun-basic/src/index.ts

@@ -23,4 +23,7 @@ const links: StartupBannerLink[] = [
 
 printStartupBanner({ name: "DaloyJS API", url, runtime: "Bun", links });
 
-export default app;
+// NOTE: This module intentionally has no default export. Bun auto-starts a
+// server from any module whose default-exported object has a `fetch` method,
+// which would collide with the explicit `serve()` call above on the same port
+// (EADDRINUSE) and crash on startup (Railway's "Uncaught exception" loop).

package/templates/cloudflare-worker/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. This starter omits `docs: true` to keep the Worker bundle small — enable it explicitly via `new App({ docs: true })` to auto-mount `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. `docs: true` is set in `new App({...})`, so `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI) are auto-mounted. DaloyJS is dependency-free and the Scalar UI loads from a CDN, so this adds negligible Worker bundle size; drop `docs` (and the `openapi` block) if you want the smallest possible bundle.
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Cloudflare Workers (Web Standard `Request`/`Response`).

package/templates/cloudflare-worker/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -70,12 +70,13 @@ pnpm audit        # supply-chain audit
 
 Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
 
-## OpenAPI & docs routes (opt-in)
+## OpenAPI & docs routes
 
-This Worker starter omits `docs: true` to keep the bundle small (Workers
-have a hard size limit). When you opt in via `new App({ docs: true })`,
-three routes are auto-mounted off the spec generated from your route
-definitions:
+This Worker starter sets `docs: true` in `new App({...})`, so three routes
+are auto-mounted off the spec generated from your route definitions.
+DaloyJS is dependency-free and the Scalar UI loads from a CDN, so the bundle
+cost is negligible; drop `docs` (and the `openapi` block) if you need the
+smallest possible Worker. The routes:
 
 - `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
 - `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as

package/templates/cloudflare-worker/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/cloudflare-worker/package.json

@@ -11,7 +11,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.1",
+    "@daloyjs/core": "^0.38.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/cloudflare-worker/src/index.ts

@@ -6,6 +6,22 @@ const app = new App({
   bodyLimitBytes: 256 * 1024,
   requestTimeoutMs: 5_000,
   production: true,
+  // Cloudflare Workers always run behind Cloudflare's edge, which sets
+  // X-Forwarded-For. Declare that single trusted hop so DaloyJS reads the real
+  // client IP instead of refusing the (otherwise spoofable) header and
+  // returning 500 in production. Increase the hop count if you put an
+  // additional proxy in front of the Worker.
+  behindProxy: { hops: 1 },
+  // daloy-minimal:strip-start docs
+  // Auto-mounted docs (since `docs: true`): GET /openapi.json, /openapi.yaml,
+  // and /docs (Scalar UI). DaloyJS is dependency-free and the Scalar UI loads
+  // from a CDN, so this adds negligible Worker bundle size. Drop `docs` (and
+  // this `openapi` block) if you want the smallest possible bundle.
+  openapi: {
+    info: { title: "My Daloy Cloudflare API", version: "0.0.1" },
+  },
+  docs: true,
+  // daloy-minimal:strip-end docs
 });
 
 app.use(requestId());

package/templates/deno-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/deno-basic/deno.json

@@ -8,10 +8,10 @@
     "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts"
   },
   "imports": {
-    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.38.1",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.38.1/banner",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.38.1/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.38.1/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.38.3",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.38.3/banner",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.38.3/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.38.3/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/deno-basic/src/build-app.ts

@@ -19,6 +19,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: Deno.env.get("DENO_ENV") === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(Deno.env.get("TRUST_PROXY_HOPS")
+      ? { behindProxy: { hops: Number(Deno.env.get("TRUST_PROXY_HOPS")) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -28,7 +41,15 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from deno.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${Deno.env.get("PORT") ?? "3000"}` }],
+      // Leave `servers` unset so the Scalar "Try it" panel and the generated
+      // client target the origin the docs are served from — the deployed
+      // domain in production, localhost in dev — which keeps "Try it" within
+      // the connect-src 'self' CSP on every platform (Deno Deploy, etc.).
+      // Never hardcode a URL here: a localhost default breaks "Try it" once
+      // deployed. Set PUBLIC_URL to pin an absolute base URL (e.g. for codegen).
+      ...(Deno.env.get("PUBLIC_URL")
+        ? { servers: [{ url: Deno.env.get("PUBLIC_URL")! }] }
+        : {}),
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/node-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/node-basic/package.json

@@ -18,7 +18,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.1",
+    "@daloyjs/core": "^0.38.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/node-basic/src/build-app.ts

@@ -20,6 +20,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(process.env.TRUST_PROXY_HOPS
+      ? { behindProxy: { hops: Number(process.env.TRUST_PROXY_HOPS) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -32,7 +45,15 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${process.env.PORT ?? 3000}` }],
+      // Leave `servers` unset so the Scalar "Try it" panel and the generated
+      // client target the origin the docs are served from — the deployed
+      // domain in production, localhost in dev — which keeps "Try it" within
+      // the connect-src 'self' CSP on every platform. Never hardcode a URL
+      // here: a localhost default breaks "Try it" once deployed. Set PUBLIC_URL
+      // to pin an absolute base URL (e.g. for client codegen).
+      ...(process.env.PUBLIC_URL
+        ? { servers: [{ url: process.env.PUBLIC_URL }] }
+        : {}),
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/node-basic/tsconfig.build.json

@@ -3,8 +3,9 @@
   "compilerOptions": {
     "declaration": true,
     "outDir": "dist",
+    "rootDir": "src",
     "sourceMap": true
   },
-  "include": ["src/**/*", "scripts/**/*"],
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "tests"]
 }

package/templates/{vercel-edge → vercel}/AGENTS.md

@@ -1,13 +1,13 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.js runtime** (Vercel's recommended runtime for standalone functions, running on Fluid Compute). **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
-- Runtime: Vercel Edge (Web Standard `Request`/`Response`).
+- Runtime: Vercel Node.js Functions on Fluid Compute (Web Standard `Request`/`Response`).
 
 ## Commands
 
-- `pnpm dev` — local Vercel dev server on http://localhost:3000
+- `pnpm dev` — local Node dev server (`src/dev.ts`) on http://localhost:3000 (no `vercel dev` / login needed; serves the same app the Vercel Function runs)
 - `pnpm typecheck` — `tsc --noEmit`
 - `pnpm test` — run test suite
 - `pnpm deploy` — deploy to Vercel
@@ -15,8 +15,9 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contrac
 
 ## Project shape
 
-- `api/[...path].ts` — Vercel Edge entrypoint. Builds the `App`, registers routes/middleware, and exports `default toWebHandler(app)` plus `export const config = { runtime: "edge" }`. **Keep it a catch-all** so DaloyJS owns routing. For Vercel's recommended Node.js runtime, remove the Edge config and export `default toFetchHandler(app)` from `@daloyjs/core/vercel`.
-- `vercel.json` — Vercel build/runtime configuration.
+- `api/index.ts` — the single Vercel Node.js Functions entrypoint. Builds the `App`, registers routes/middleware, and exports `default toFetchHandler(app)` from `@daloyjs/core/vercel` (Node.js Functions expect a default export with a `fetch` method; Node.js is the default runtime, so no `runtime` export is needed). `vercel.json` rewrites every path (`/(.*)` → `/api`) to this one function, so DaloyJS owns all routing and the app's routes are served at the site root (`/healthz`, `/docs`, …), not under `/api/*`. If you specifically need the Edge runtime, add `export const runtime = "edge"` and switch to `default toWebHandler(app)`.
+- `vercel.json` — Vercel config. The `rewrites` rule routing all paths to `/api` is **required** for root routing; do not remove it. (`functions` sets memory / maxDuration.)
+- `src/dev.ts` — local Node dev server (`pnpm dev`). Imports the `app` exported from `api/index.ts` and serves it via `@daloyjs/core/node` at the root, so you get fast local iteration without `vercel dev`. Dev-only; it is not under `api/`, so Vercel never deploys it.
 - `tests/` — test files.
 
 ## Imports
@@ -24,7 +25,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contrac
 This project uses TypeScript with `"allowImportingTsExtensions"`, so relative imports use the **`.ts` extension** — the actual file you see on disk:
 
 ```ts
-import handler from "../api/[...path].ts";
+import handler from "../api/index.ts";
 ```
 
 You import the file you see. Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly, and the test runner (tsx) does too. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
@@ -36,8 +37,8 @@ You import the file you see. Vercel bundles the `api/` functions at deploy time
 3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields.
 4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core`.
 5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. For production traffic, back rate-limiting with Vercel KV or another shared store (the in-memory limiter resets per instance).
-6. Stay on the Edge runtime: only Web Standards APIs. No `node:` modules, no `fs`, no `Buffer`. If a feature requires Node, switch to a Node-runtime template.
-7. The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS handles routing.
+6. On the Node.js runtime the full Node API is available (`node:*`, `Buffer`, `fs`), but prefer Web Standards (`Request`/`Response`, `fetch`, Web Crypto) so the same app can also run on the Edge runtime or another adapter unchanged. If you opt into the Edge runtime, drop `node:` modules entirely.
+7. Keep a single `api/index.ts` entry and the `vercel.json` `/(.*)` → `/api` rewrite so DaloyJS handles all routing at the site root.
 8. Every new route ships with a test that covers a happy path and at least one unhappy path.
 
 ## Secure-by-default (do not let an AI strip these)
@@ -48,8 +49,8 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. Keep `responses[N].body` schemas tight; never widen to `z.any()` to let a privileged field escape.
 - Every protected route attaches an auth `beforeHandle` and ships an unhappy-path test proving an unauthenticated request returns `401` (and wrong scope returns `403`) — the HTTP-boundary equivalent of Supabase's pgTAP policy tests.
 - JWT verifiers keep an explicit `algorithms` allowlist; never trust the token's `alg` header, never allow `none`, always check `exp` / `nbf`.
-- Credential / HMAC comparisons use `crypto.subtle.timingSafeEqual`, never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
-- Keep `api/[...path].ts` a catch-all so DaloyJS owns routing — do not split into per-path files that bypass the middleware chain.
+- Credential / HMAC comparisons use a constant-time comparison (the framework's `timingSafeEqual`), never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
+- Keep the single `api/index.ts` entry and the `vercel.json` rewrite so DaloyJS owns routing — do not split into per-path files that bypass the middleware chain, and do not remove the rewrite (the root domain would 404).
 - `.env`, `.env.local`, secrets, private keys: never commit. Use `vercel env` for production secrets.
 
 ## Process expectations

package/templates/{vercel-edge → vercel}/README.md

@@ -1,6 +1,6 @@
 # my-daloy-vercel-api
 
-A [DaloyJS](https://daloyjs.dev) Vercel Edge API starter.
+A [DaloyJS](https://daloyjs.dev) Vercel API starter on the Node.js runtime.
 
 ## Develop
 
@@ -26,8 +26,8 @@ curl http://localhost:3000/books/1
 - OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 
-After deploying, the same routes serve `/docs`, `/openapi.json`, and `/openapi.yaml` from your Vercel Edge URL.
-To brand Scalar, change `docs: true` in `api/[...path].ts` to `docs: { scalar: { theme, customCss } }`.
+After deploying, the same routes serve `/docs`, `/openapi.json`, and `/openapi.yaml` from your Vercel deployment URL.
+To brand Scalar, change `docs: true` in `api/index.ts` to `docs: { scalar: { theme, customCss } }`.
 
 <!-- daloy-minimal:strip-end docs -->
 
@@ -37,32 +37,46 @@ To brand Scalar, change `docs: true` in `api/[...path].ts` to `docs: { scalar: {
 pnpm deploy
 ```
 
-The API entry lives at `api/[...path].ts` and uses `@daloyjs/core/vercel`:
+The API entry lives at `api/index.ts` and uses `@daloyjs/core/vercel`:
 
 ```ts
-export const config = { runtime: "edge" };
-export default toWebHandler(app);
+import { toFetchHandler } from "@daloyjs/core/vercel";
+
+// Node.js is the default runtime — no `runtime` export needed.
+export default toFetchHandler(app);
 ```
 
-This starter defaults to Vercel's Edge runtime for compatibility with the
-`vercel-edge` template name. Vercel now recommends Node.js for new projects;
-for Node.js Functions, remove the `config` export and use the official default
-`{ fetch }` shape instead:
+This starter targets Vercel's Node.js runtime (on Fluid Compute), which Vercel
+now recommends for standalone functions. Node.js Functions expect a default
+export with a `fetch` method, which is exactly what `toFetchHandler(app)`
+returns. If you specifically need the Edge runtime, add the `runtime` export and
+switch to the bare web handler:
 
 ```ts
-import { toFetchHandler } from "@daloyjs/core/vercel";
+import { toWebHandler } from "@daloyjs/core/vercel";
 
-export default toFetchHandler(app);
+export const runtime = "edge";
+export default toWebHandler(app);
+```
+
+`vercel.json` rewrites every path to this single function:
+
+```json
+{ "rewrites": [{ "source": "/(.*)", "destination": "/api" }] }
 ```
 
-That catch-all API route lets DaloyJS own routing while Vercel handles the runtime.
+So DaloyJS owns all routing and the app's routes are served at the **site root**
+(`/healthz`, `/docs`, `/openapi.json`, …) rather than under `/api/*`. Without
+this rewrite the function only answers `/api/*` and the root domain returns a
+Vercel 404. (The demo defines no `/` route, so the bare root returns the app's
+problem+json 404 — visit `/docs` or `/healthz`.)
 
 ## Imports
 
 This project uses TypeScript with `"allowImportingTsExtensions"`. Relative imports use the `.ts` extension — the actual file on disk:
 
 ```ts
-import handler from "../api/[...path].ts";
+import handler from "../api/index.ts";
 ```
 
 Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly, and the test runner (tsx) does too.
@@ -70,7 +84,7 @@ Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly,
 ## What's included
 
 - `@daloyjs/core/vercel` with starter security middleware: `secureHeaders` and `requestId`.
-- Smaller edge-friendly body and timeout limits in the generated app.
+- Smaller serverless-friendly body and timeout limits in the generated app.
 <!-- daloy-minimal:strip-start books -->
 - A health route and a contract-first `/books/:id` route with Zod validation.
   <!-- daloy-minimal:strip-end books -->

package/templates/{vercel-edge → vercel}/_Dockerfile

@@ -1,8 +1,8 @@
 # syntax=docker/dockerfile:1.7
-# Containerized local-dev / CI environment for a DaloyJS Vercel Edge API.
+# Containerized local-dev / CI environment for a DaloyJS Vercel API.
 #
 # Production deploys go through `vercel deploy` to Vercel's managed
-# Edge runtime — **this Dockerfile is not a production runtime**. Ship
+# Node.js runtime — **this Dockerfile is not a production runtime**. Ship
 # the function to Vercel; use this image for:
 #   - Reproducible local dev (devcontainers, GitHub Codespaces).
 #   - CI smoke tests that exercise the handler against `vercel dev`

package/templates/{vercel-edge → vercel}/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -2,20 +2,21 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  Vercel Edge. Use when adding or changing HTTP routes, Zod schemas,
-  middleware, or error handling; regenerating the OpenAPI spec or the typed
-  Hey API client; keeping the catch-all Edge entrypoint and Web-Standard
-  runtime constraints; or working on auth, rate limits, secrets, and the
+  Vercel (Node.js runtime). Use when adding or changing HTTP routes, Zod
+  schemas, middleware, or error handling; regenerating the OpenAPI spec or the
+  typed Hey API client; keeping the single Vercel Functions entrypoint and
+  Web-Standard handler; or working on auth, rate limits, secrets, and the
   project's quality gates.
 license: MIT
 ---
 
-# SKILL.md — DaloyJS best practices (Vercel Edge)
+# SKILL.md — DaloyJS best practices (Vercel, Node.js runtime)
 
 Operational guidance and best practices for AI coding agents working in this
-DaloyJS **Vercel Edge** project. This is the project's **single source of
-truth** for how to add routes, write tests, ship secure defaults, and run
-the quality gates. Read this in full before making non-trivial changes.
+DaloyJS **Vercel** project on the **Node.js runtime** (Fluid Compute). This is
+the project's **single source of truth** for how to add routes, write tests,
+ship secure defaults, and run the quality gates. Read this in full before
+making non-trivial changes.
 
 ## When to use this skill
 
@@ -24,18 +25,21 @@ Use this skill when you need to:
 - Add, modify, or remove HTTP routes in this project.
 - Adjust middleware, validation, or error handling.
 - Run tests or typecheck the project.
-- Deploy or troubleshoot the Edge runtime entrypoint.
+- Deploy or troubleshoot the Vercel Functions entrypoint.
 - Harden the API (auth, CORS, rate limits, secrets, dependency hygiene).
 
 Do **not** use this skill for tasks unrelated to the API itself.
 
 ## Core principles
 
-DaloyJS is a **contract-first** framework. On Vercel Edge, additionally:
+DaloyJS is a **contract-first** framework. On Vercel, additionally:
 
-1. **Stay on the Edge runtime.** Only Web Standards APIs (no `node:`
-   modules, no `fs`, no `Buffer`). If a feature requires Node APIs, the
-   user must switch to a Node template.
+1. **Node.js runtime by default.** The full Node API is available
+   (`node:*`, `Buffer`, `fs`), but prefer Web Standards (`Request` /
+   `Response`, `fetch`, Web Crypto) so the same app can also run on the
+   Edge runtime or another adapter unchanged. Opt into Edge only when you
+   need it (`export const runtime = "edge"` + `toWebHandler(app)`), and
+   then drop `node:` modules.
 2. **The route definition is the contract.** Method, path, request
    schemas, and response schemas live in one place (`app.route({...})`).
 3. **Zod schemas validate at every boundary.**
@@ -43,23 +47,30 @@ DaloyJS is a **contract-first** framework. On Vercel Edge, additionally:
 5. **Secure by default.** `requestId()`, `secureHeaders()`, and
    `rateLimit()` are registered before route definitions. Note the
    in-memory rate limiter resets per instance — for high-traffic
-   deployments, prefer Vercel's native rate-limiting (e.g.
-   `@vercel/edge` + KV) or an external store.
-6. **One catch-all entrypoint.** `api/[...path].ts` owns all routing so
-   DaloyJS can generate a unified OpenAPI spec.
+   deployments, back it with an external shared store (e.g. Upstash
+   Redis).
+6. **One entrypoint + a rewrite.** `api/index.ts` is the only function,
+   and `vercel.json` rewrites every path (`/(.*)` → `/api`) to it, so
+   DaloyJS owns all routing at the site root and generates a unified
+   OpenAPI spec. Removing the rewrite makes the root domain 404.
 
 ## Project shape
 
-- `api/[...path].ts` — the Edge entrypoint. Builds the `App`, registers
-  routes/middleware, and exports `default toWebHandler(app)` plus
-  `export const config = { runtime: "edge" }`.
-- `vercel.json` — Vercel build/runtime configuration.
+- `api/index.ts` — the Vercel Functions entrypoint. Builds the `App`,
+  registers routes/middleware, and exports `default toFetchHandler(app)`
+  (Node.js Functions expect a default export with a `fetch` method; Node.js
+  is the default runtime, so no `runtime` export is needed).
+- `vercel.json` — Vercel config. The `rewrites` rule (`/(.*)` → `/api`) is
+  required so DaloyJS routes at the site root; do not remove it.
+- `src/dev.ts` — local Node dev server (`pnpm dev`). Serves the `app`
+  exported from `api/index.ts` via `@daloyjs/core/node`; dev-only, never
+  deployed (it lives outside `api/`).
 - `tests/` — test files (`*.test.ts`).
 
 ## Commands cheat-sheet
 
 ```bash
-pnpm dev          # local Vercel dev server on http://localhost:3000
+pnpm dev          # local Node dev server (src/dev.ts) on http://localhost:3000
 pnpm typecheck    # tsc --noEmit
 pnpm test         # run test suite
 pnpm deploy       # deploy to Vercel
@@ -82,13 +93,13 @@ definitions:
 Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
 `openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
 mount only outside production, or `docs: false` to disable all three.
-On Vercel Edge the YAML serializer is pure-string (no Node deps) and
-adds <1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is
-exported from `@daloyjs/core/openapi`.
+On Vercel the YAML serializer is pure-string (no extra deps) and adds
+<1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is exported
+from `@daloyjs/core/openapi`.
 
 ## Workflow: add a new route
 
-1. **Open `api/[...path].ts`.**
+1. **Open `api/index.ts`.**
 2. **Design schemas first.** Use `z.object({...}).strict()` for inputs.
 3. **Call `app.route({...})`** with `method`, `path`, `operationId`,
    `tags`, `responses`, `handler` (plus `request` when accepting input).
@@ -151,18 +162,19 @@ Add CORS only when needed, with an explicit `origin` allowlist.
 
 ## Testing best practices
 
-Tests use in-process `app.request(...)` — no port, no Edge runtime
+Tests use in-process `app.request(...)` — no port, no Vercel runtime
 needed for unit tests.
 
 ```ts
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import handler from "../api/[...path].ts";
+import handler from "../api/index.ts";
 
-// Either import the underlying app, or test via the Edge handler's
-// fetch interface by passing a Web Request.
+// Either import the underlying app, or test via the handler's fetch
+// method (the default export is the Vercel `{ fetch }` object) by
+// passing a Web Request.
 test("GET /healthz returns ok", async () => {
-  const res = await handler(new Request("http://local/healthz"));
+  const res = await handler.fetch(new Request("http://local/healthz"));
   assert.equal(res.status, 200);
 });
 ```
@@ -180,23 +192,25 @@ Aim for **100% line and function coverage** on the routes you add.
   production traffic, back rate-limiting with Vercel KV or another
   shared store so limits apply across instances.
 - Never log secrets — filter `authorization`, `cookie`, etc.
-- Read secrets from `process.env` (available on Edge). Validate via Zod
-  at module load.
+- Read secrets from `process.env` (available on Node.js Functions).
+  Validate via Zod at module load.
 - For auth, verify JWT signatures with the Web Crypto API
-  (`crypto.subtle`). Never trust the `alg` header from the token.
+  (`crypto.subtle`, available on both Node.js and Edge). Never trust the
+  `alg` header from the token.
 - Validate redirects against an allowlist.
 - Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
   mitigate DoS.
-- Edge functions have small bundle and CPU limits; be cautious about
-  adding heavy dependencies. Inspect bundle size during deploy.
-- Pin Vercel project settings (regions, runtime version) explicitly in
-  `vercel.json` rather than relying on dashboard defaults.
+- Serverless functions still have bundle-size and cold-start costs; be
+  cautious about adding heavy dependencies. Inspect bundle size during
+  deploy.
+- Pin Vercel project settings (regions, memory, maxDuration) explicitly
+  in `vercel.json` rather than relying on dashboard defaults.
 
 ## Logging & observability
 
 - Use `ctx.log` — it carries the request id.
-- `console.log` on Edge shows up in Vercel's runtime logs; the framework
-  logger emits structured JSON for log aggregators.
+- `console.log` shows up in Vercel's runtime logs; the framework logger
+  emits structured JSON for log aggregators.
 
 ## Configuration & secrets
 
@@ -205,17 +219,19 @@ Aim for **100% line and function coverage** on the routes you add.
 
 ## Pitfalls and guardrails
 
-- The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS
-  handles routing. Do not split routes into multiple Vercel API files
-  unless the user explicitly asks (it disables shared middleware and a
-  unified OpenAPI).
-- Use `toWebHandler(app)` from `@daloyjs/core/vercel` for Edge — never
-  hand-roll a `fetch(req)` adapter. For Vercel's recommended Node.js
-  runtime, remove the Edge config and export `default toFetchHandler(app)`.
+- Keep the single `api/index.ts` entry and the `vercel.json` `/(.*)` →
+  `/api` rewrite so DaloyJS handles routing at the site root. Do not
+  remove the rewrite (the root domain would 404) and do not split routes
+  into multiple Vercel API files unless the user explicitly asks (it
+  disables shared middleware and a unified OpenAPI).
+- Use `toFetchHandler(app)` from `@daloyjs/core/vercel` for Node.js
+  Functions — never hand-roll a `fetch(req)` adapter. If you opt into the
+  Edge runtime, use `toWebHandler(app)` with `export const runtime = "edge"`.
 - Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
   `@daloyjs/core` and `@daloyjs/core/vercel`.
-- Avoid Node-only APIs (`Buffer`, `fs`, full `process` API). If a
-  feature needs Node, switch to a Node-runtime template.
+- Node APIs (`Buffer`, `fs`, full `process`) are available on the Node.js
+  runtime, but keep handlers Web-Standard where practical so the app can
+  also run on the Edge runtime unchanged.
 - Do not weaken response literal types (`as const`).
 - Do not return errors as `{ status: 4xx, body }`. Throw a typed error.
 - Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).

package/templates/vercel/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/vercel/api/index.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { App, NotFoundError, requestId, secureHeaders } from "@daloyjs/core";
+import { toFetchHandler } from "@daloyjs/core/vercel";
+
+// This template targets Vercel's Node.js runtime — the runtime Vercel now
+// recommends for standalone functions (it runs on Fluid Compute, with the
+// performance of the edge network but full Node API support). Node.js is the
+// default runtime, so no `runtime` export is needed. Vercel Node.js Functions
+// expect a default export with a `fetch` method, which is exactly what
+// `toFetchHandler(app)` returns. If you specifically need the Edge runtime
+// instead, add `export const runtime = "edge"` and switch the default export to
+// `toWebHandler(app)` from "@daloyjs/core/vercel".
+//
+// This single function owns ALL routing: `vercel.json` rewrites every path to
+// `/api`, and DaloyJS matches the original request path (`/healthz`, `/docs`,
+// …). So the app's routes are served at the site root, not under `/api/*`.
+// Do not split this into per-path files — keep one entry so the middleware
+// chain and the generated OpenAPI spec stay unified.
+
+// Exported so the local dev server (`src/dev.ts`, run by `pnpm dev`) can serve
+// the same app over a plain Node listener. Vercel uses the default export below.
+export const app = new App({
+  bodyLimitBytes: 256 * 1024,
+  requestTimeoutMs: 5_000,
+  production: process.env.NODE_ENV === "production",
+  // Reverse-proxy posture. On Vercel, every request reaches the function
+  // through Vercel's edge, which sets `x-forwarded-for`. The app must declare
+  // that trusted hop, otherwise DaloyJS refuses the spoofable header and
+  // returns 500 in production. Vercel is exactly one edge hop, so the default
+  // is 1; override TRUST_PROXY_HOPS only if you put another proxy in front
+  // (e.g. set it to 2 behind Cloudflare -> Vercel).
+  behindProxy: { hops: Number(process.env.TRUST_PROXY_HOPS ?? "1") },
+  // daloy-minimal:strip-start docs
+  // Auto-mounted docs (when `docs: true`):
+  //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
+  //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
+  //   GET /docs         — Scalar API reference UI that loads the spec
+  openapi: {
+    info: { title: "My Daloy Vercel API", version: "0.0.1" },
+  },
+  docs: true,
+  // daloy-minimal:strip-end docs
+});
+
+app.use(requestId());
+app.use(secureHeaders());
+
+app.route({
+  method: "GET",
+  path: "/healthz",
+  operationId: "healthz",
+  tags: ["Ops"],
+  responses: {
+    200: {
+      description: "Service is healthy",
+      body: z.object({ ok: z.literal(true), runtime: z.literal("vercel") }),
+    },
+  },
+  handler: async () => ({
+    status: 200,
+    body: { ok: true as const, runtime: "vercel" as const },
+  }),
+});
+
+// daloy-minimal:strip-start books
+const Book = z.object({ id: z.string(), title: z.string() });
+const books = new Map<string, z.infer<typeof Book>>([
+  ["1", { id: "1", title: "Noli Me Tangere" }],
+]);
+
+app.route({
+  method: "GET",
+  path: "/books/:id",
+  operationId: "getBookById",
+  tags: ["Books"],
+  request: { params: z.object({ id: z.string() }) },
+  responses: {
+    200: { description: "Found", body: Book },
+    404: { description: "Not found" },
+  },
+  handler: async ({ params }) => {
+    const book = books.get(params.id);
+    if (!book) throw new NotFoundError(`Book ${params.id} not found`);
+    return { status: 200, body: book };
+  },
+});
+// daloy-minimal:strip-end books
+
+export default toFetchHandler(app);

package/templates/{vercel-edge → vercel}/package.json

@@ -4,14 +4,14 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vercel dev",
+    "dev": "node --import tsx/esm src/dev.ts",
     "deploy": "vercel deploy",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test tests/**/*.test.ts",
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.1",
+    "@daloyjs/core": "^0.38.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/vercel/src/dev.ts

@@ -0,0 +1,16 @@
+// Local development server.
+//
+// Vercel runs `api/index.ts` as a Function in production; this serves the very
+// same app over a plain Node listener so you get fast local iteration without
+// `vercel dev` (no Vercel login, no edge emulation). Routes are served at the
+// root here (`/healthz`, `/docs`, …), exactly as on the deployed site — in
+// production the `vercel.json` rewrite maps every path to the Function.
+//
+// Run with: `pnpm dev` (or `npm run dev`).
+import { serve } from "@daloyjs/core/node";
+import { app } from "../api/index.ts";
+
+const port = Number(process.env.PORT ?? 3000);
+serve(app, { port });
+// eslint-disable-next-line no-console
+console.log(`DaloyJS dev server listening on http://localhost:${port}`);

package/templates/vercel/tests/app.test.ts

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import handler from "../api/index.ts";
+
+test("Vercel Node.js handler responds through DaloyJS", async () => {
+  // Vercel Node.js Functions invoke the default export's `fetch` method.
+  const response = await handler.fetch(new Request("https://example.test/healthz"));
+  assert.equal(response.status, 200);
+  assert.equal((await response.json()).runtime, "vercel");
+});

package/templates/{vercel-edge → vercel}/tsconfig.json

@@ -15,5 +15,5 @@
     "noEmit": true,
     "allowImportingTsExtensions": true
   },
-  "include": ["api/**/*.ts", "tests/**/*.ts"]
+  "include": ["api/**/*.ts", "src/**/*.ts", "tests/**/*.ts"]
 }

package/templates/vercel/vercel.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "rewrites": [{ "source": "/(.*)", "destination": "/api" }],
+  "functions": {
+    "api/index.ts": { "memory": 1024, "maxDuration": 30 }
+  }
+}

package/templates/vercel-edge/api/[...path].ts

@@ -1,70 +0,0 @@
-import { z } from "zod";
-import { App, NotFoundError, requestId, secureHeaders } from "@daloyjs/core";
-import { toWebHandler } from "@daloyjs/core/vercel";
-
-// This template defaults to Vercel's Edge runtime for compatibility with the
-// existing `vercel-edge` starter. For Vercel's recommended Node.js runtime,
-// remove this config and export `toFetchHandler(app)` from @daloyjs/core/vercel.
-export const config = { runtime: "edge" };
-
-const app = new App({
-  bodyLimitBytes: 256 * 1024,
-  requestTimeoutMs: 5_000,
-  production: process.env.NODE_ENV === "production",
-  // daloy-minimal:strip-start docs
-  // Auto-mounted docs (when `docs: true`):
-  //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
-  //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
-  //   GET /docs         — Scalar API reference UI that loads the spec
-  openapi: {
-    info: { title: "My Daloy Edge API", version: "0.0.1" },
-  },
-  docs: true,
-  // daloy-minimal:strip-end docs
-});
-
-app.use(requestId());
-app.use(secureHeaders());
-
-app.route({
-  method: "GET",
-  path: "/healthz",
-  operationId: "healthz",
-  tags: ["Ops"],
-  responses: {
-    200: {
-      description: "Service is healthy",
-      body: z.object({ ok: z.literal(true), runtime: z.literal("vercel-edge") }),
-    },
-  },
-  handler: async () => ({
-    status: 200,
-    body: { ok: true as const, runtime: "vercel-edge" as const },
-  }),
-});
-
-// daloy-minimal:strip-start books
-const Book = z.object({ id: z.string(), title: z.string() });
-const books = new Map<string, z.infer<typeof Book>>([
-  ["1", { id: "1", title: "Noli Me Tangere" }],
-]);
-
-app.route({
-  method: "GET",
-  path: "/books/:id",
-  operationId: "getBookById",
-  tags: ["Books"],
-  request: { params: z.object({ id: z.string() }) },
-  responses: {
-    200: { description: "Found", body: Book },
-    404: { description: "Not found" },
-  },
-  handler: async ({ params }) => {
-    const book = books.get(params.id);
-    if (!book) throw new NotFoundError(`Book ${params.id} not found`);
-    return { status: 200, body: book };
-  },
-});
-// daloy-minimal:strip-end books
-
-export default toWebHandler(app);

package/templates/vercel-edge/tests/app.test.ts

@@ -1,9 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import handler from "../api/[...path].ts";
-
-test("Vercel Edge handler responds through DaloyJS", async () => {
-  const response = await handler(new Request("https://example.test/healthz"));
-  assert.equal(response.status, 200);
-  assert.equal((await response.json()).runtime, "vercel-edge");
-});

package/templates/vercel-edge/vercel.json

@@ -1,4 +0,0 @@
-{
-  "version": 2,
-  "cleanUrls": true
-}