create-daloy 0.38.2 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.38.2",
+  "version": "0.39.0",
   "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:2bbd5e7e-5035-5e09-92c8-3e1aec60f5a1",
+  "serialNumber": "urn:uuid:ed023484-5e0b-5534-bab9-c4cb2527b814",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-16T14:42:42.888Z",
+    "timestamp": "2026-06-17T18:08:50.010Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.38.2"
+        "version": "0.39.0"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@0.38.2",
+      "bom-ref": "pkg:npm/create-daloy@0.39.0",
       "name": "create-daloy",
-      "version": "0.38.2",
+      "version": "0.39.0",
       "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.2",
+      "purl": "pkg:npm/create-daloy@0.39.0",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-0.38.2",
+        "tagId": "swidtag-create-daloy-0.39.0",
         "name": "create-daloy",
-        "version": "0.38.2",
+        "version": "0.39.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@0.38.2",
+      "ref": "pkg:npm/create-daloy@0.39.0",
       "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.2",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.2-2bbd5e7e-5035-5e09-92c8-3e1aec60f5a1",
+  "name": "create-daloy-0.39.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.39.0-ed023484-5e0b-5534-bab9-c4cb2527b814",
   "creationInfo": {
-    "created": "2026-06-16T14:42:42.888Z",
+    "created": "2026-06-17T18:08:50.010Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "0.38.2",
+      "versionInfo": "0.39.0",
       "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.2"
+          "referenceLocator": "pkg:npm/create-daloy@0.39.0"
         }
       ]
     }

package/templates/bun-basic/package.json

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

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

@@ -40,19 +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: {
-      // Advertise the public origin so the Scalar "Try it" panel calls the
-      // deployed URL (and stays within the connect-src 'self' CSP) instead of
-      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
-      // the local dev port.
-      servers: [
-        {
-          url:
-            process.env.PUBLIC_URL ??
-            (process.env.RAILWAY_PUBLIC_DOMAIN
-              ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`
-              : `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/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/package.json

@@ -11,7 +11,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.2",
+    "@daloyjs/core": "^0.39.0",
     "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/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.2",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.38.2/banner",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.38.2/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.38.2/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.39.0",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.39.0/banner",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.39.0/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.39.0/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

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

@@ -41,19 +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: {
-      // Advertise the public origin so the Scalar "Try it" panel calls the
-      // deployed URL (and stays within the connect-src 'self' CSP) instead of
-      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
-      // the local dev port.
-      servers: [
-        {
-          url:
-            Deno.env.get("PUBLIC_URL") ??
-            (Deno.env.get("RAILWAY_PUBLIC_DOMAIN")
-              ? `https://${Deno.env.get("RAILWAY_PUBLIC_DOMAIN")}`
-              : `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/package.json

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

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

@@ -45,19 +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: {
-      // Advertise the public origin so the Scalar "Try it" panel calls the
-      // deployed URL (and stays within the connect-src 'self' CSP) instead of
-      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
-      // the local dev port.
-      servers: [
-        {
-          url:
-            process.env.PUBLIC_URL ??
-            (process.env.RAILWAY_PUBLIC_DOMAIN
-              ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`
-              : `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/vercel/AGENTS.md

@@ -7,7 +7,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.j
 
 ## 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** on the **Node.j
 
 ## Project shape
 
-- `api/[...path].ts` — 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). **Keep it a catch-all** so DaloyJS owns routing. If you specifically need the Edge runtime, add `export const runtime = "edge"` and switch to `default toWebHandler(app)`.
-- `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** on the **Node.j
 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.
@@ -37,7 +38,7 @@ You import the file you see. Vercel bundles the `api/` functions at deploy time
 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. 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. The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS handles routing.
+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)
@@ -49,7 +50,7 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - 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 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 `api/[...path].ts` a catch-all so DaloyJS owns routing — do not split into per-path files that bypass the middleware chain.
+- 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/README.md

@@ -27,7 +27,7 @@ curl http://localhost:3000/books/1
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 
 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/[...path].ts` to `docs: { scalar: { theme, customCss } }`.
+To brand Scalar, change `docs: true` in `api/index.ts` to `docs: { scalar: { theme, customCss } }`.
 
 <!-- daloy-minimal:strip-end docs -->
 
@@ -37,7 +37,7 @@ 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
 import { toFetchHandler } from "@daloyjs/core/vercel";
@@ -59,14 +59,24 @@ export const runtime = "edge";
 export default toWebHandler(app);
 ```
 
-That catch-all API route lets DaloyJS own routing while Vercel handles the runtime.
+`vercel.json` rewrites every path to this single function:
+
+```json
+{ "rewrites": [{ "source": "/(.*)", "destination": "/api" }] }
+```
+
+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.

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

@@ -4,7 +4,7 @@ description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
   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 catch-all Vercel Functions entrypoint and
+  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
@@ -49,22 +49,28 @@ DaloyJS is a **contract-first** framework. On Vercel, additionally:
    in-memory rate limiter resets per instance — for high-traffic
    deployments, back it with an external shared store (e.g. Upstash
    Redis).
-6. **One catch-all entrypoint.** `api/[...path].ts` owns all routing so
-   DaloyJS can generate a unified OpenAPI spec.
+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 Vercel Functions entrypoint. Builds the `App`,
+- `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 build/runtime configuration.
+- `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
@@ -93,7 +99,7 @@ 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).
@@ -162,7 +168,7 @@ 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 handler's fetch
 // method (the default export is the Vercel `{ fetch }` object) by
@@ -213,10 +219,11 @@ 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).
+- 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"`.

package/templates/vercel/api/{[...path].ts → index.ts}

@@ -6,15 +6,30 @@ import { toFetchHandler } from "@daloyjs/core/vercel";
 // 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
-// in `/api` expect a default export with a `fetch` method, which is exactly
-// what `toFetchHandler(app)` returns. If you specifically need the Edge runtime
+// 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.
 
-const app = new App({
+// 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)

package/templates/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.2",
+    "@daloyjs/core": "^0.39.0",
     "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

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import handler from "../api/[...path].ts";
+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.

package/templates/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

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