create-nifra 3.5.0 → 4.0.2

package/template-batteries/tsconfig.json

@@ -12,5 +12,5 @@
     "types": ["bun"],
     "skipLibCheck": true
   },
-  "include": ["src/**/*"]
+  "include": ["backend/**/*"]
 }

package/template-isr/README.md

@@ -27,6 +27,9 @@ holds across `hit`s and bumps on a `miss`/regeneration.
 
 ## How it works
 
+`backend/worker.ts` is the Workers entry and `backend/dev-server.ts` the local Bun server; both wrap
+the same app, and `build.ts` builds the client bundle and the worker.
+
 - `withISR(app, { store, revalidate, now })` wraps the app's `fetch`. Only full-document `text/html`
   `GET` `200`s are cached; assets, soft-nav data fetches, redirects, and errors pass through.
 - A route sets its freshness with `export const revalidate = <seconds>` (see `routes/index.tsx`).

package/template-isr/{backend.ts → backend/app.ts}

@@ -1,3 +1,4 @@
+import { responseContract } from "@nifrajs/core/response-contract"
 import { server } from "@nifrajs/core/server"
 import {
   cors,
@@ -30,6 +31,7 @@ export const backend = server({
   requestTimeoutMs: 30_000,
   admission: createAdmissionController({ maxInFlight: 128, maxQueue: 0 }),
 })
+  .use(responseContract("enforce"))
   .use(securityHeaders())
   .use(
     cors({

package/template-isr/{server.ts → backend/dev-server.ts}

@@ -1,6 +1,6 @@
 /**
  * Local Bun dev server (no wrangler) - the same app with an in-memory ISR store. `bun run dev:bun`
- * after `bun run build`. Production uses Workers KV (worker.ts); the only line that changes is the
+ * after `bun run build`. Production uses Workers KV (backend/worker.ts); the only line that changes is the
  * store. Watch the `x-nifra-isr` response header: miss → hit → stale.
  */
 import { inProcessClient } from "@nifrajs/client"
@@ -8,9 +8,9 @@ import { createWebApp, MemoryCacheStore, revalidateEndpoint, withISR } from "@ni
 import type { BuildManifest } from "@nifrajs/web/build"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import { reactAdapter } from "@nifrajs/web-react"
-import { backend } from "./backend"
+import { backend } from "./app"
 
-const publicDir = `${import.meta.dir}/public`
+const publicDir = `${import.meta.dir}/../public`
 const assets = JSON.parse(
   await Bun.file(`${publicDir}/assets/manifest.json`)
     .text()
@@ -19,7 +19,7 @@ const assets = JSON.parse(
 
 const app = createWebApp({
   adapter: reactAdapter,
-  manifest: discoverRoutes(`${import.meta.dir}/routes`),
+  manifest: discoverRoutes(`${import.meta.dir}/../routes`),
   clientEntry: assets.entry,
   routePreload: assets.routes,
   api: inProcessClient(backend),

package/template-isr/{worker.ts → backend/worker.ts}

@@ -12,7 +12,7 @@ import {
   withISR,
 } from "@nifrajs/web"
 import { reactAdapter } from "@nifrajs/web-react"
-import { backend } from "./backend"
+import { backend } from "./app"
 // Generated by build.ts (buildServer): the static-import route manifest + the baked client entry URL.
 import { clientEntry, manifest } from "./server-manifest"
 
@@ -41,7 +41,9 @@ export default {
 
     // On-demand purge: POST /__nifra/revalidate?path=/ with the secret in x-nifra-revalidate-token.
     if (new URL(req.url).pathname === "/__nifra/revalidate") {
-      return revalidateEndpoint({ store, secret: env.REVALIDATE_SECRET ?? "" })(req)
+      // No secret configured means no purge endpoint - never an open one.
+      if (env.REVALIDATE_SECRET === undefined) return new Response("Not Found", { status: 404 })
+      return revalidateEndpoint({ store, secret: env.REVALIDATE_SECRET })(req)
     }
 
     // Cache GET documents stale-while-revalidate. Default 60s; a route's `export const revalidate`

package/template-isr/build.ts

@@ -7,6 +7,8 @@ const dir = import.meta.dir
 const client = await buildClient({
   routesDir: `${dir}/routes`,
   outDir: `${dir}/public/assets`,
+  // public/ is generated Workers Assets output; copying it into public/assets would recurse.
+  publicDir: false,
   clientModule: "@nifrajs/web-react/client",
   conditions: ["bun", "browser"],
   define: { "process.env.NODE_ENV": '"production"' },
@@ -14,7 +16,7 @@ const client = await buildClient({
 
 const { worker } = await buildServer({
   routesDir: `${dir}/routes`,
-  serverEntry: `${dir}/worker.ts`,
+  serverEntry: `${dir}/backend/worker.ts`,
   outDir: `${dir}/dist-server`,
   clientEntry: client.entry,
 })

package/template-isr/gitignore

@@ -4,4 +4,10 @@ dist-server
 .build
 .wrangler
 # generated by buildServer next to the entry
-server-manifest.ts
+backend/server-manifest.ts
+# generated by nifra: route types and dev-server entries
+.nifra/
+# local secrets; commit .env.example instead
+.env
+.env.*
+!.env.example

package/template-isr/nifra.assurance.ts

@@ -11,7 +11,7 @@
  * an exemption you get by leaving the rule off is one nobody ever sees.
  */
 import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
-import { backend } from "./backend"
+import { backend } from "./backend/app"
 
 export default defineAssuranceConfig({
   source: backend,
@@ -34,19 +34,21 @@ export default defineAssuranceConfig({
       // the route modules - is what keeps every route's declaration equal to its reach. The drivers
       // below are the backstop for code that goes around the seam; they grant both, because an import
       // cannot tell a read from a write.
+      // Shared starter catalog: an absent database integration is optional, but any matching
+      // import still grants its capabilities. Remove optional for seams this app owns.
       imports: [
-        { specifier: "./read.ts", capabilities: ["db.read"] },
-        { specifier: "./write.ts", capabilities: ["db.write"] },
-        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"] },
-        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"] },
-        { specifier: "pg", capabilities: ["db.read", "db.write"] },
-        { specifier: "postgres", capabilities: ["db.read", "db.write"] },
-        { specifier: "mysql2", capabilities: ["db.read", "db.write"] },
-        { specifier: "kysely", capabilities: ["db.read", "db.write"] },
-        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"] },
-        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"] },
-        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"] },
-        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"] },
+        { specifier: "./read.ts", capabilities: ["db.read"], optional: true },
+        { specifier: "./write.ts", capabilities: ["db.write"], optional: true },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "pg", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"], optional: true },
       ],
       // Add a driver here to force every query through the seam, and the check will name any route that
       // reaches around it: `{ specifier: "pg", reason: "query through db/read.ts or db/write.ts" }`.

package/template-isr/package.json

@@ -5,22 +5,23 @@
   "private": true,
   "scripts": {
     "build": "bun run build.ts",
-    "dev": "bunx wrangler dev",
-    "dev:bun": "bun run server.ts",
+    "dev": "bunx wrangler dev --var NIFRA_ALLOW_MEMORY_RATE_LIMIT:true",
+    "dev:bun": "bun run backend/dev-server.ts",
     "check": "nifra check && nifra assure"
   },
   "dependencies": {
-    "@nifrajs/client": "^3.5.0",
-    "@nifrajs/core": "^3.5.0",
-    "@nifrajs/middleware": "^3.5.0",
-    "@nifrajs/schema": "^3.5.0",
-    "@nifrajs/web": "^3.5.0",
-    "@nifrajs/web-react": "^3.5.0",
+    "@nifrajs/client": "^4.0.2",
+    "@nifrajs/core": "^4.0.2",
+    "@nifrajs/middleware": "^4.0.2",
+    "@nifrajs/schema": "^4.0.2",
+    "@nifrajs/web": "^4.0.2",
+    "@nifrajs/web-react": "^4.0.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^3.5.0",
+    "@nifrajs/cli": "^4.0.2",
+    "@types/bun": "^1.4.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3"

package/template-isr/routes/index.backend.ts

@@ -0,0 +1,14 @@
+import { t } from "@nifrajs/schema"
+import type { Route } from "./+types/index"
+
+// ISR: the `withISR` wrapper (worker.ts / server.ts) caches this page and serves it
+// stale-while-revalidate. `revalidate` is the freshness window in SECONDS - nifra emits it as the
+// `x-nifra-isr-revalidate` header, which the wrapper reads to set this page's TTL.
+export const revalidate = 10
+
+export const loaderOutput = t.object({ renders: t.number(), revalidate: t.number() })
+
+export async function loader({ api }: Route.LoaderArgs) {
+  const res = await api.page.get()
+  return { renders: res.ok ? res.data.renders : 0, revalidate }
+}

package/template-isr/routes/index.tsx

@@ -1,32 +1,20 @@
-import type { LoaderArgs, LoaderData } from "@nifrajs/client"
-import type { backend } from "../backend"
+import type { Route } from "./+types/index"
 
 export const meta = {
   title: "nifra + ISR",
   meta: [{ name: "description", content: "Incremental Static Regeneration on nifra." }],
 }
 
-// ISR: the `withISR` wrapper (worker.ts / server.ts) caches this page and serves it
-// stale-while-revalidate. `revalidate` is the freshness window in SECONDS - nifra emits it as the
-// `x-nifra-isr-revalidate` header, which the wrapper reads to set this page's TTL. Loader/meta are
-// pure annotated exports, so they tree-shake out of the client bundle.
-export const revalidate = 10
-
-export async function loader({ api }: LoaderArgs<typeof backend>) {
-  const res = await api.page.get()
-  return { renders: res.ok ? res.data.renders : 0 }
-}
-
-export default function Home(props: { data: LoaderData<typeof loader> }) {
+export default function Home(props: Route.ComponentProps) {
   return (
     <section>
       <p>
         server renders: <b>{props.data.renders}</b>
       </p>
       <p>
-        Reload within {revalidate}s and this holds - you're served the cached page (response header{" "}
-        <code>x-nifra-isr: hit</code>). After the window, the next request gets the stale page
-        instantly (<code>stale</code>) while a fresh copy regenerates behind it. Edit{" "}
+        Reload within {props.data.revalidate}s and this holds - you're served the cached page
+        (response header <code>x-nifra-isr: hit</code>). After the window, the next request gets the
+        stale page instantly (<code>stale</code>) while a fresh copy regenerates behind it. Edit{" "}
         <code>routes/index.tsx</code> to begin.
       </p>
     </section>

package/template-isr/tsconfig.json

@@ -10,7 +10,8 @@
     "skipLibCheck": true,
     "noEmit": true,
     "verbatimModuleSyntax": true,
-    "types": ["react", "react-dom"]
+    "types": ["bun", "react", "react-dom"],
+    "rootDirs": [".", "./.nifra/types"]
   },
   "include": ["**/*.ts", "**/*.tsx"],
   "exclude": [
@@ -20,9 +21,9 @@
     ".build",
     ".nifra",
     ".wrangler",
-    "server-manifest.ts",
-    "server.ts",
-    "worker.ts",
+    "backend/server-manifest.ts",
+    "backend/dev-server.ts",
+    "backend/worker.ts",
     "build.ts"
   ]
 }

package/template-isr/wrangler.toml

@@ -1,6 +1,11 @@
 name = "nifra-isr"
 main = "dist-server/worker.js"
-compatibility_date = "2025-01-01"
+# 2025-04-01 or later: from that date `nodejs_compat` fills `process.env` from the Worker's variables,
+# where backend/app.ts reads NIFRA_ALLOW_MEMORY_RATE_LIMIT; until that variable is "true" the deployed
+# Worker refuses to start. Set it (a Worker variable, or [vars] below) only if a per-isolate rate limit
+# will do: Cloudflare runs many isolates and each counts alone. `bun run dev` sets it for its one local
+# process.
+compatibility_date = "2025-04-01"
 compatibility_flags = ["nodejs_compat"]
 
 # Workers Assets: the content-hashed client bundle (buildClient → ./public/assets) is served at

package/template-site/README.md

@@ -7,7 +7,6 @@ is Web-standard, so only the server entry + build target differ per platform.
 ```sh
 bun install
 bun run dev        # nifra dev → true-HMR dev server (Bun + nifra SSR) at http://localhost:3000
-bun run preview    # wrangler pages dev dist → preview the built Cloudflare bundle (run `bun run build` first)
 ```
 
 The backend starter includes response security headers, explicit-origin CORS, a 30-second request
@@ -16,35 +15,37 @@ production unless `NIFRA_ALLOW_MEMORY_RATE_LIMIT=true`; use a shared store for m
 For cookie sessions, add signed CSRF middleware and require both runtime authentication and CSRF
 evidence in `nifra.assurance.ts`.
 
-Edit `routes/index.tsx` (the landing + a live loader/action counter), add files under `routes/`
-(`about.tsx` → `/about`, `[id].tsx` → `:id`, nested `_layout.tsx` for sections), and put your data
-behind `backend.ts`.
+Edit `routes/index.tsx` (the landing) and `routes/index.backend.ts` (its live loader/action
+counter), add files under `routes/` (`about.tsx` → `/about`, `[id].tsx` → `:id`, nested `_layout.tsx`
+for sections; a page's loader/action goes in its `x.backend.ts`), and put your data behind
+`backend/app.ts`.
 
-## Deploy - pick a target
+## Deploy
 
-| target | build | deploy |
+The app deploys to the `target` in `nifra.config.ts` (chosen with `bun create nifra --target`, switched
+with `nifra target <t>`). `bun run build` runs `nifra build`, which generates that target's server
+entry from `backend/` and `routes/`, so the app carries no per-runtime entry or build script.
+
+| target | `bun run build` emits | then |
 | --- | --- | --- |
-| **Bun** (flagship) | `bun run build:bun` | `bun run start` (`bun dist-bun/server-bun.js`) - any host |
-| **Node** | `bun run build:node` | `docker build -t app . && docker run -p 3000:3000 app` (or `bun run start:node`) |
-| **Deno Deploy** | `bun run build:deno` | `deployctl deploy --prod --entrypoint=dist-deno/server-deno.js` (or `deno task start`) |
-| **Cloudflare Pages** | `bun run build` | `bun run deploy:cf` (`wrangler pages deploy dist`) |
-| **Vercel Edge** | `bun run build:vercel` | `bun run deploy:vercel` (`vercel deploy --prebuilt`) |
+| **bun** (default) | `dist/server.js` + assets | `bun dist/server.js` on any host (`--docker` adds a Dockerfile) |
+| **node** | `dist/server.js` + assets | `node dist/server.js` (`--docker` adds a Dockerfile) |
+| **deno** | `dist/server.js` + assets | `deployctl deploy --prod --entrypoint=dist/server.js` |
+| **cloudflare** | `dist/` (`_worker.js`, `_routes.json`) | `wrangler pages deploy dist` |
+| **vercel** | `.vercel/output/` (Build Output API) | `vercel deploy --prebuilt` |
 
-The routes, `backend.ts`, and the client bundle are shared; each `build*` script swaps
-`buildServer`'s target/conditions and the server entry. nifra never enters your cloud credentials - the
-configs (`Dockerfile`, `deno.json`, `wrangler.toml`, Vercel Build Output API) are scaffolded; you run
-the vendor CLI.
+nifra never enters your cloud credentials: it writes the target's config (`wrangler.toml`,
+`deno.json`, a `Dockerfile`) and you run the vendor CLI.
 
 ## Structure
 
 ```
 routes/        index.tsx (landing), _layout.tsx (chrome), _404.tsx
-framework.ts   the render adapter (imported by the server entries - kept edge-bundlable)
-nifra.config.ts the nifra CLI's dev/build config (adapter + clientModule) - read by `nifra dev`
-backend.ts     your contract (loaders/actions call it in-process)
-server-bun.ts  Bun entry (Bun.serve)         build-bun.ts    → dist-bun/
-_worker.ts     Cloudflare Pages entry        build.ts        → dist/
-server-node.ts Node entry (@nifrajs/node)       build-node.ts   → dist-node/   (Dockerfile)
-server-deno.ts Deno entry (@nifrajs/deno)       build-deno.ts   → dist-deno/    (deno.json)
-server-vercel.ts Vercel Edge function        build-vercel.ts → .vercel/output/
+               index.backend.ts - the landing page's loader/action (server only)
+backend/       app.ts - your contract (loaders/actions call it in-process)
+               framework.ts - the render adapter (imported by the server entry `nifra build` generates - kept edge-bundlable)
+frontend/      browser-only code (components, hooks) - created when you need it
+shared/        code both sides import (types, formatting, validation) - may import only shared code
+nifra.config.ts the nifra CLI's dev/build config (adapter + clientModule) - read by `nifra dev` and `nifra build`,
+               including `target`, where `nifra build` deploys
 ```

package/template-site/{backend.ts → backend/app.ts}

@@ -1,4 +1,5 @@
 import { server } from "@nifrajs/core/server"
+import { responseContract } from "@nifrajs/core/response-contract"
 import {
   MemoryStore,
   cors,
@@ -9,10 +10,10 @@ import {
 import { counter } from "./counter"
 
 // Your backend contract - page loaders/actions call it in-process during SSR (no network).
-// Name and location are load-bearing: `nifra dev|build|check` resolve `backend.ts` from the project
-// root, the same fixed convention as `routes/`, `framework.ts`, and `nifra.config.ts`. Rename or move
-// it and the CLI runs without a backend (no error - the file is optional). Only THIS entry file is
-// pinned to the root; the modules it merges can live in any directory you like.
+// Name and location are load-bearing: `nifra dev|build|check` resolve `backend/app.ts`, the same
+// fixed convention as `routes/`, `backend/framework.ts`, and `nifra.config.ts`. Rename or move it and
+// the CLI runs without a backend (no error - the file is optional). The modules it merges live beside
+// it under `backend/`, which never reaches the browser.
 //
 // Composition only: this module merges route modules and registers none of its own.
 //
@@ -30,6 +31,7 @@ export const backend = server({
   requestTimeoutMs: 30_000,
   admission: createAdmissionController({ maxInFlight: 128, maxQueue: 0 }),
 })
+  .use(responseContract("enforce"))
   .use(securityHeaders())
   .use(
     cors({

package/template-site/gitignore

@@ -1,19 +1,14 @@
 node_modules
 dist
-dist-bun
-dist-node
-dist-deno
+.nifra-build
 .vercel
-.build
-.build-bun
-.build-node
-.build-deno
-.build-vercel
 .wrangler
-# generated by buildServer next to the entry
-server-manifest.ts
 # generated by `nifra dev` at the project root: the Vite pipeline's client entry, the Bun pipeline's
 # client entry + HTML, and the Bun pipeline's generated bunfig/boundary plugin.
 .nifra-vite-entry.tsx
 .nifra-bun/
 .nifra/
+# local secrets; commit .env.example instead
+.env
+.env.*
+!.env.example

package/template-site/nifra.assurance.ts

@@ -11,7 +11,7 @@
  * an exemption you get by leaving the rule off is one nobody ever sees.
  */
 import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
-import { backend } from "./backend"
+import { backend } from "./backend/app"
 
 export default defineAssuranceConfig({
   source: backend,
@@ -34,19 +34,21 @@ export default defineAssuranceConfig({
       // the route modules - is what keeps every route's declaration equal to its reach. The drivers
       // below are the backstop for code that goes around the seam; they grant both, because an import
       // cannot tell a read from a write.
+      // Shared starter catalog: an absent database integration is optional, but any matching
+      // import still grants its capabilities. Remove optional for seams this app owns.
       imports: [
-        { specifier: "./read.ts", capabilities: ["db.read"] },
-        { specifier: "./write.ts", capabilities: ["db.write"] },
-        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"] },
-        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"] },
-        { specifier: "pg", capabilities: ["db.read", "db.write"] },
-        { specifier: "postgres", capabilities: ["db.read", "db.write"] },
-        { specifier: "mysql2", capabilities: ["db.read", "db.write"] },
-        { specifier: "kysely", capabilities: ["db.read", "db.write"] },
-        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"] },
-        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"] },
-        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"] },
-        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"] },
+        { specifier: "./read.ts", capabilities: ["db.read"], optional: true },
+        { specifier: "./write.ts", capabilities: ["db.write"], optional: true },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "pg", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"], optional: true },
       ],
       // Add a driver here to force every query through the seam, and the check will name any route that
       // reaches around it: `{ specifier: "pg", reason: "query through db/read.ts or db/write.ts" }`.

package/template-site/nifra.config.ts

@@ -1,7 +1,7 @@
-// The nifra CLI's config - read by `nifra dev|build|start`. Separate from `framework.ts` (which the
-// edge/server entries import, so it must stay edge-bundlable): THIS file is imported only by the CLI
-// (which runs on Bun), so it's the place for CLI-only build/dev tooling. React JSX is Bun-native,
+// The nifra CLI's config - read by `nifra dev|build|start`. Separate from `backend/framework.ts`
+// (which the generated server entry imports, so it must stay edge-bundlable): THIS file is imported only
+// by the CLI (which runs on Bun), so it's the place for CLI-only build/dev tooling. React JSX is Bun-native,
 // so the default dev loop needs no Vite plugin.
 
-export { adapter } from "./framework"
+export { adapter } from "./backend/framework"
 export const clientModule = "@nifrajs/web-react/client"

package/template-site/routes/index.backend.ts

@@ -0,0 +1,18 @@
+import { t } from "@nifrajs/schema"
+import type { Route } from "./+types/index"
+
+export const loaderOutput = t.object({ count: t.number() })
+
+// Loader runs on the server (in-process during SSR). The action handles the form POST; after a
+// client submit the loader revalidates with no full reload (progressive enhancement).
+export async function loader({ api }: Route.LoaderArgs) {
+  const res = await api.count.get()
+  return { count: res.ok ? res.data.count : 0 }
+}
+
+export const actionOutput = t.object({ ok: t.boolean() })
+
+export async function action({ api }: Route.ActionArgs) {
+  await api.count.post()
+  return { ok: true }
+}

package/template-site/routes/index.tsx

@@ -1,24 +1,11 @@
-import type { ActionArgs, LoaderArgs, LoaderData } from "@nifrajs/client"
-import type { backend } from "../backend"
+import type { Route } from "./+types/index"
 
 export const meta = {
   title: "nifra site",
   meta: [{ name: "description", content: "A nifra + React SSR site, deployable to every runtime." }],
 }
 
-// Loader runs on the server (in-process during SSR). The action handles the form POST; after a
-// client submit the loader revalidates with no full reload (progressive enhancement).
-export async function loader({ api }: LoaderArgs<typeof backend>) {
-  const res = await api.count.get()
-  return { count: res.ok ? res.data.count : 0 }
-}
-
-export async function action({ api }: ActionArgs<typeof backend>) {
-  await api.count.post()
-  return { ok: true }
-}
-
-export default function Home(props: { data: LoaderData<typeof loader> }) {
+export default function Home(props: Route.ComponentProps) {
   return (
     <>
       <section className="hero">

package/template-site-preact/README.md

@@ -7,7 +7,6 @@ is Web-standard, so only the server entry + build target differ per platform.
 ```sh
 bun install
 bun run dev        # nifra dev → true-HMR dev server (Bun + nifra SSR) at http://localhost:3000
-bun run preview    # wrangler pages dev dist → preview the built Cloudflare bundle (run `bun run build` first)
 ```
 
 The backend starter includes response security headers, explicit-origin CORS, a 30-second request
@@ -18,32 +17,34 @@ evidence in `nifra.assurance.ts`.
 
 Routes are Preact function components (JSX, via `jsxImportSource: "preact"`) under `routes/` -
 `index.tsx` (landing + a live loader/action counter), `_layout.tsx` (chrome), `_404.tsx`. The
-frontend adapter is one line in `framework.ts`; data lives behind `backend.ts`.
+frontend adapter is one line in `backend/framework.ts`; data lives behind `backend/app.ts`.
 
-## Deploy - pick a target
+## Deploy
 
-| target | build | deploy |
+The app deploys to the `target` in `nifra.config.ts` (chosen with `bun create nifra --target`, switched
+with `nifra target <t>`). `bun run build` runs `nifra build`, which generates that target's server
+entry from `backend/` and `routes/`, so the app carries no per-runtime entry or build script.
+
+| target | `bun run build` emits | then |
 | --- | --- | --- |
-| **Bun** (flagship) | `bun run build:bun` | `bun run start` - any host |
-| **Node** | `bun run build:node` | `docker build -t app . && docker run -p 3000:3000 app` (or `bun run start:node`) |
-| **Deno Deploy** | `bun run build:deno` | `deployctl deploy --prod --entrypoint=dist-deno/server-deno.js` |
-| **Cloudflare Pages** | `bun run build` | `bun run deploy:cf` |
-| **Vercel Edge** | `bun run build:vercel` | `bun run deploy:vercel` |
+| **bun** (default) | `dist/server.js` + assets | `bun dist/server.js` on any host (`--docker` adds a Dockerfile) |
+| **node** | `dist/server.js` + assets | `node dist/server.js` (`--docker` adds a Dockerfile) |
+| **deno** | `dist/server.js` + assets | `deployctl deploy --prod --entrypoint=dist/server.js` |
+| **cloudflare** | `dist/` (`_worker.js`, `_routes.json`) | `wrangler pages deploy dist` |
+| **vercel** | `.vercel/output/` (Build Output API) | `vercel deploy --prebuilt` |
 
-The routes, `backend.ts`, and the client bundle are shared; each `build*` script swaps `buildServer`'s
-target/conditions and the server entry. nifra never enters your cloud credentials - it scaffolds the
-configs (`Dockerfile`, `deno.json`, `wrangler.toml`, Vercel Build Output API); you run the vendor CLI.
+nifra never enters your cloud credentials: it writes the target's config (`wrangler.toml`,
+`deno.json`, a `Dockerfile`) and you run the vendor CLI.
 
 ## Structure
 
 ```
 routes/        index.tsx (landing), _layout.tsx (chrome), _404.tsx
-framework.ts   the adapter (preactAdapter) - imported by the server entries (edge-bundlable)
-nifra.config.ts the nifra CLI's dev/build config (adapter + clientModule) - read by `nifra dev`
-backend.ts     your contract (loaders/actions call it in-process)
-server-bun.ts  Bun entry (Bun.serve)         build-bun.ts    → dist-bun/
-_worker.ts     Cloudflare Pages entry        build.ts        → dist/
-server-node.ts Node entry (@nifrajs/node)       build-node.ts   → dist-node/   (Dockerfile)
-server-deno.ts Deno entry (@nifrajs/deno)       build-deno.ts   → dist-deno/    (deno.json)
-server-vercel.ts Vercel Edge function        build-vercel.ts → .vercel/output/
+               index.backend.ts - the landing page's loader/action (server only)
+backend/       app.ts - your contract (loaders/actions call it in-process)
+               framework.ts - the adapter (preactAdapter) - imported by the server entry `nifra build` generates (edge-bundlable)
+frontend/      browser-only code (components, hooks) - created when you need it
+shared/        code both sides import (types, formatting, validation) - may import only shared code
+nifra.config.ts the nifra CLI's dev/build config (adapter + clientModule) - read by `nifra dev` and `nifra build`,
+               including `target`, where `nifra build` deploys
 ```

package/template-site-preact/nifra.config.ts

@@ -1,7 +1,7 @@
-// The nifra CLI's config - read by `nifra dev|build|start`. Separate from `framework.ts` (which the
-// edge/server entries import, so it must stay edge-bundlable): THIS file is imported only by the CLI
-// (which runs on Bun), so it's the place for CLI-only build/dev tooling. Preact JSX is Bun-native,
+// The nifra CLI's config - read by `nifra dev|build|start`. Separate from `backend/framework.ts`
+// (which the generated server entry imports, so it must stay edge-bundlable): THIS file is imported only
+// by the CLI (which runs on Bun), so it's the place for CLI-only build/dev tooling. Preact JSX is Bun-native,
 // so the default dev loop needs no Vite plugin.
 
-export { adapter } from "./framework"
+export { adapter } from "./backend/framework"
 export const clientModule = "@nifrajs/web-preact/client"

package/template-site-preact/routes/_layout.tsx

@@ -22,7 +22,9 @@ const css = `
 export default function Layout(props: { children?: ComponentChildren }) {
   return (
     <div id="app">
-      <style>{css}</style>
+      {/* Raw: the server renderer escapes text children, and a <style> element's text is never
+          unescaped, so a quoted font name would arrive as &quot; and void the rule. */}
+      <style dangerouslySetInnerHTML={{ __html: css }} />
       <header className="site">
         <div className="wrap">
           <a href="/" className="logo">