netjes 0.0.2 → 0.0.4

package/template/_AGENTS.md

@@ -12,11 +12,17 @@ How this app is built, for coding agents and the people working with them. It is
 
 | Path | What |
 |---|---|
-| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted; `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. |
+| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted. Netjes renders `<html>`, `<head>` and `<body>` around the root layout, so no layout renders them: the root one returns what goes inside `<body>`. `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. A mounted page package's pages, layouts and boundaries merge into these folders under its prefix, from `node_modules`. `document.test.ts` renders the home page's whole document, as the server sends it, with `renderDocument` from `netjes/testing`. |
 | `Features/` | The C# side, one folder per feature (`namespace __NAME__.Features.Home`): page loaders (`MapPageLoader`), layout loaders (`MapLayoutLoader`), server actions (`MapAction`) and JSON endpoints, with records for what they take and return. Each feature has a `Map...` extension method that `Program.cs` calls. |
-| `Program.cs` | Services and the pipeline: `AddNetjes`, `UseNetjes`, authentication (when you add it), `UseAntiforgery`, each feature's `Map...`, and `app.MapPages()` last. |
+| `Program.cs` | Services and the pipeline: `AddNetjes`, `UseNetjes`, authentication (when you add it), `UseAntiforgery`, each page package's mount and each feature's `Map...`, and `app.MapPages()` last. |
 | `components/` | React components, with their Vitest tests next to them (`*.test.tsx`). |
-| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `route()` and the `Href` type. Never edit it. |
+<!--netjes:if tests-->
+| `tests/__NAME__.Tests/` | The C# tests: a new test of a loader or an action goes here. In the project `netjes new` writes, on xUnit v3, `AppFactory.cs` runs the real app in memory with `WebApplicationFactory`, with no Node and no client build, and `HomePageTests.cs` requests the home page and posts its form as the client router does. C# for the app does not go in the root folders `tests/` and `e2e/`, which `netjes new` leaves out of the app's build (`DefaultItemExcludes` in `__NAME__.csproj`). |
+<!--netjes:end-->
+<!--netjes:if e2e-->
+| `e2e/` | Playwright tests, which `npm run test:e2e` runs. The `playwright.config.ts` that `netjes new` writes runs them against the app twice: in Development (the Vite dev server) and in Production (the build). |
+<!--netjes:end-->
+| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `endpointUrl()` for the URLs of the app's endpoints, `route()` and the `Href` type, the pages of mounted page packages included. Never edit it. |
 | `styles/global.css` | Tailwind CSS (`@import 'tailwindcss'`), imported by `app/layout.tsx`. |
 | `public/` | Static files, served at the site root. `favicon.svg` is the Netjes mark, linked by `icons` in the root layout's `metadata`; replace it with the app's own. |
 
@@ -25,8 +31,14 @@ How this app is built, for coding agents and the people working with them. It is
 ```bash
 npm run dev                 # dotnet watch + Vite HMR on http://localhost:5080; rewrites generated/netjes.ts on start
 npm test                    # Vitest
-npm run typecheck           # strict TypeScript
+npm run typecheck           # strict TypeScript; in the configs netjes new writes, the app's code without Node's types
 dotnet build                # C#, warnings are errors
+<!--netjes:if tests-->
+dotnet test tests/__NAME__.Tests   # the C# tests; a plain dotnet test here finds only the app's project and runs none
+<!--netjes:end-->
+<!--netjes:if e2e-->
+npm run test:e2e            # Playwright (run npx playwright install chromium once first)
+<!--netjes:end-->
 npx netjes generate         # rewrite generated/netjes.ts after changing a C# type (--check: fail when stale)
 npm run routes              # the route table as ASP.NET Core sees it, with route warnings
 npx netjes build            # types, then the client and server bundles
@@ -39,7 +51,7 @@ dotnet publish -c Release   # runs the build and ships dist/
 2. Call its `Map...` method from `Program.cs`, before `app.MapPages()`.
 3. Run `npx netjes generate` (or restart `npm run dev`).
 4. Write `app/blog/[slug]/page.tsx`: `export default definePage(pages['/blog/[slug]'], function Post({ post }) { ... })`.
-5. Test the component with Vitest and `createTestApp` from `netjes/testing`; run the checks below.
+5. Test the loader in C# (in `tests/__NAME__.Tests`, where the app has it) and the component with Vitest and `createTestApp` from `netjes/testing`; run the checks below.
 
 A page without a loader is a plain default export and gets empty props. Forms call server actions: `app.MapAction("posts.like", ...)` in C#, `useAction(serverActions['posts.like'])` and `<Form action={formAction}>` in React; they also work without JavaScript.
 
@@ -47,18 +59,35 @@ A page without a loader is a plain default export and gets empty props. Forms ca
 
 - C# decides: data access, validation, authorization (`.RequireAuthorization()` on a loader, a layout loader or `MapPages()`; `Page.Forbidden()`), redirects and caching. React renders what the loader sends; hiding a button is not access control.
 - Never edit `generated/netjes.ts`. Change the C# type and regenerate; commit the file with the change. CI runs `npx netjes generate --check`.
-- zod at every boundary: `definePage` and `defineLayout` with the generated schemas, `useSearchParams(schema)` and `useParams(schema)` for the URL, `api['GET /api/...'].response.parse(...)` for JSON you fetch, `usePublicConfig(schema)` for public config, `Href` (or `isHref`) from the generated file for URLs that come from data. No `any`, no casts of server data.
+- zod at every boundary: `definePage` and `defineLayout` with the generated schemas (extended, as in `pages['/x'].extend({ link: Href })`, only where no C# type fits), `useSearchParams(schema)` and `useParams(schema)` for the URL, `api['GET /api/...'].response.parse(...)` for JSON you fetch from `useHref(endpointUrl('GET /api/...', params))`, `usePublicConfig(schema)` for public config, `Href` (or `isHref`) from the generated file for URLs that come from data, such as a CMS. No `any`, no casts of server data.
+- A link that C# sends to one of the app's pages is a `Href` in the C# record (`new Href("/about")`): it is generated as the `Href` schema, checked against the pages when the props are parsed, and goes to `<Link href>` as it is. C# checks only its shape, and a root-relative `Href` that no page serves fails the whole page, so a link to an endpoint or a file stays a `string`.
 - Server state goes through TanStack Query (`useQuery`), not `useEffect` and `fetch`. Seed it from the loader with `.WithQuery(key, data)` so it is server-rendered; actions update it with `.Invalidate(key)` or `.WithQuery(key, data)`.
-- Internal links are `<Link href={route('/blog/[slug]', { slug })}>`; a typo in an href is a type error.
+- Internal links are `<Link href={route('/blog/[slug]', { slug })}>`; a typo in an href is a type error. `route(pattern, params, search, { hash })` builds the query from `search` and a `#fragment` from `hash`, the id of an element on the page; pass `undefined` as `search` for a link with a fragment and no query.
+- After a client navigation to another page, the router starts the focus over at the top of the document, as a page load does, and announces the page to screen readers by its title. Keep the "Skip to content" link the first thing in `app/layout.tsx` that takes the focus, with the content in `<main id="content">`, and give each page a title of its own (`metadata`, or `PageMetadata` from C#): the router says nothing for a page whose title is the previous page's.
 - Action inputs are records with `init` properties: `public sealed record NoteInput { [Required] public string? Text { get; init; } public bool Pinned { get; init; } }`. A field the post leaves out, such as an unchecked checkbox, keeps its default; form binding refuses (400) a post that lacks one of a positional record's constructor fields. DataAnnotations on them (`[Required]`, `[StringLength]`) are checked before the action runs and come back as field errors, with no setup, also for a post that has none of the input's fields. Return `ServerAction.Invalid(field, message)` for other errors the user can fix.
-- `.CachePage(...)` only for pages that are the same for every visitor: their loaders and shared props must not depend on cookies or other per-visitor state.
-- `Netjes:PublicConfig` is sent to the browser: never put secrets there.
+- `.CachePage(...)` only for pages that are the same for every visitor: their loaders and shared props must not depend on cookies or other per-visitor state. In the Development environment pages are never output-cached (each request renders them), so check caching on `npx netjes build && npx netjes start`, or in a `WebApplicationFactory` test in the `Testing` environment with `Netjes:Mode` set to `Development`, as the `AppFactory.cs` that `netjes new` writes runs. Each query string as sent is an entry of its own: name the keys a cached page reads with `.CacheQueryKeys("page")`, or `.CacheQueryKeys()` for none, so other query strings render without being stored (`.claude/skills/netjes/references/caching-and-streaming.md`).
+- In the TypeScript configs `netjes new` writes, `tsconfig.app.json` checks the app's code without Node's types, so a component or page that reads `process` or imports `node:*` fails `npm run typecheck`. Code that runs only in Node goes in `scripts/`, which `tsconfig.node.json` checks with them; do not add `node` to the `types` of `tsconfig.app.json`.
+- An `error.tsx` renders `error.message` only when `!error.withheld`, and shows `error.status ?? 500` if it shows a status.
+- `Netjes:PublicConfig` is sent to the browser: never put secrets there. So is the route of each endpoint with an `endpointUrl` key, one mapped only in Development included, once any component calls `endpointUrl`: keep secrets out of routes, and authorize on the endpoint ([security](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/security.md#errors-and-configuration)).
+- Page packages (pages, layouts, loaders and actions from an npm and NuGet package pair) are mounted, never copied into `app/`: the package's extension in `Program.cs` before `app.MapPages()`, at a prefix in folder syntax (`app.MapHelpCenter("/help")`, `"/(marketing)/help"`), and the npm name in `netjes({ packages })` in `vite.config.ts`. Install both halves at one version. Its files merge into `app/` folder by folder, so an app page in its folder renders inside its layouts. An app page of the same shape as one of its pages stops the app: replace the package's page with `.Override("/help/contact")` on the mount, reading the props from the package's generated file. Conventions on the mount cover only the package's pages; protect the app's own pages under the prefix as usual. For a package that draws its own shell, keep `app/layout.tsx` to providers and the skip link, and put the site's chrome in `app/(site)/layout.tsx`. Run `npx netjes generate` after updating a package ([page packages](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/page-packages.md)).
 - Write the failing test first, then the change.
 
 ## Before you finish
 
+<!--netjes:if tests-->
+```bash
+npm test && npm run typecheck && dotnet build && dotnet test tests/__NAME__.Tests && npx netjes generate --check
+```
+<!--netjes:else-->
 ```bash
 npm test && npm run typecheck && dotnet build && npx netjes generate --check
 ```
 
+No C# test project was at `tests/__NAME__.Tests/` when this file was written. If the app has C# tests elsewhere, run them too; [testing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md#c-tests-of-loaders-and-actions) says how to add a project there. After adding one, run `npx netjes agents --force`, which writes this file again with it, and `CLAUDE.md` and `.claude/skills/netjes/` too; keep your own additions to them with `git diff`.
+<!--netjes:end-->
+
 Then `npm run routes` should print no warnings, and the page should work in `npm run dev`, including with JavaScript turned off for forms.
+<!--netjes:if e2e-->
+
+For a change to a page or a form, also run `npm run test:e2e`.
+<!--netjes:end-->

package/template/__NAME__.csproj

@@ -5,6 +5,8 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <!-- The SDK compiles everything below this file: the C# tests and the Playwright specs have builds of their own. -->
+    <DefaultItemExcludes>$(DefaultItemExcludes);tests/**;e2e/**</DefaultItemExcludes>
   </PropertyGroup>
 
 <!--NETJES_REFERENCES-->

package/template/app/document.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment node
+// The home page's whole document, as the server sends it to a crawler, from the props its C# loader returns
+// (Features/Home/HomePage.cs). renderDocument renders without a DOM, as the server does, hence the node environment.
+import { CSP_SCRIPT_HASHES } from 'netjes';
+import { inlineScriptHashes, renderDocument } from 'netjes/testing';
+import { describe, expect, it } from 'vitest';
+
+const home = () =>
+  renderDocument('app/page.tsx', {
+    props: { message: 'Hello from C#', renderedAt: '2026-11-05T12:00:00Z' },
+    shared: { siteName: '__TITLE__' },
+  });
+
+describe('the home page', () => {
+  it("is a document with the loader's heading, inside the root layout", async () => {
+    const html = await home();
+
+    expect(html.startsWith('<!DOCTYPE html><html lang="en">')).toBe(true);
+    expect(html).toMatch(/<h1[^>]*>Hello from C#<\/h1>/);
+    expect(html).toContain('<nav aria-label="Main"');
+  });
+
+  it('has no inline script in its document but the one whose hash Netjes lists for a policy without a nonce', async () => {
+    // NetjesContentSecurityPolicy.ScriptHashes in C# holds the same hashes. The inline code of an afterInteractive or
+    // lazyOnload <Script> is added in the browser and is in no document: its hash goes in the policy, not here. That of
+    // a beforeInteractive <Script> is in the document: its hash goes in both.
+    expect(await inlineScriptHashes(await home())).toEqual(CSP_SCRIPT_HASHES.split(' '));
+  });
+});

package/template/app/error.tsx

@@ -5,8 +5,9 @@ export default function ErrorPage({ error, reset }: ErrorPageProps) {
   return (
     <section role="alert" className="space-y-4">
       <h1 className="text-3xl font-bold tracking-tight">Something went wrong</h1>
-      {/* In development the message can take several lines: a syntax error comes with a code frame. */}
-      <p className="whitespace-pre-wrap wrap-anywhere text-slate-600">{error.message}</p>
+      {/* Withheld: a stand-in for a message Netjes does not show, such as an exception's with error details off. A
+          message can take several lines: in development a syntax error comes with a code frame. */}
+      {!error.withheld && <p className="whitespace-pre-wrap wrap-anywhere text-slate-600">{error.message}</p>}
       <button type="button" onClick={reset} className="cursor-pointer rounded-full bg-slate-900 px-4 py-2 font-medium text-white">
         Try again
       </button>

package/template/app/layout.tsx

@@ -14,6 +14,15 @@ export default function RootLayout({ children }: LayoutProps) {
   const site = useSharedProps(sharedProps);
   return (
     <div className="mx-auto min-h-screen max-w-3xl px-6 py-10 font-sans text-slate-900">
+      {/* The first element Tab reaches, after a page load and after every client navigation, when the router starts
+          the focus over at the top of the document. It points to a place on this page, which needs no prefetch. */}
+      <Link
+        href="#content"
+        prefetch="none"
+        className="sr-only focus:not-sr-only focus:fixed focus:top-3 focus:left-3 focus:z-50 focus:rounded focus:bg-white focus:px-4 focus:py-2 focus:shadow"
+      >
+        Skip to content
+      </Link>
       <header className="mb-12 flex items-baseline justify-between">
         <Link href="/" className="text-xl font-semibold no-underline">
           {site.siteName}
@@ -27,7 +36,7 @@ export default function RootLayout({ children }: LayoutProps) {
           </Link>
         </nav>
       </header>
-      <main>{children}</main>
+      <main id="content">{children}</main>
     </div>
   );
 }

package/template/docker-compose.override.yml

@@ -1,11 +1,12 @@
-# Development: dotnet watch for C#, the Vite dev server for pages (HMR on 5173). Open http://localhost:8080.
-# Both ports are bound to localhost only: dev error pages show stack traces and Vite serves the source.
+# Development: dotnet watch for C#, the Vite dev server for pages (HMR on 5173). Open http://localhost:8080, or the port
+# APP_PORT names. Both ports are bound to localhost only: dev error pages show stack traces and Vite serves the source.
 services:
   app:
     build:
       target: dev
     ports:
-      - "127.0.0.1:8080:8080"
+      # The host's port for the app: APP_PORT, from the shell or a .env file next to this file, or 8080. Vite keeps 5173.
+      - "127.0.0.1:${APP_PORT:-8080}:8080"
       - "127.0.0.1:5173:5173"
     volumes:
       - .:/src

package/template/docker-compose.prod.yml

@@ -3,7 +3,8 @@ services:
   app:
     restart: always
     ports:
-      - "8080:8080"
+      # The host's port: APP_PORT, from the shell or a .env file next to this file, or 8080.
+      - "${APP_PORT:-8080}:8080"
     read_only: true
     tmpfs:
       - /tmp

package/template/e2e/home.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from '@playwright/test';
+
+// These tests pass with or without hydration: a link and a form work before the client router runs. A test that needs
+// the client, such as one that clicks a button with an onClick handler, first waits for it after each full page load:
+//   await expect(page.locator('html')).toHaveAttribute('data-netjes-hydrated', '');
+
+test('the home page shows the message from its C# loader', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Hello from C#');
+});
+
+test('the link on the home page leads to the about page', async ({ page }) => {
+  await page.goto('/');
+
+  await page.getByRole('link', { name: 'About this app' }).click();
+
+  await expect(page).toHaveURL('/about');
+  await expect(page.getByRole('heading', { level: 1 })).toHaveText('About');
+});
+
+test.describe('with JavaScript turned off', () => {
+  test.use({ javaScriptEnabled: false });
+
+  test('the form asks for the name it did not get', async ({ page }) => {
+    await page.goto('/');
+
+    await page.getByRole('button', { name: 'Say hello' }).click();
+
+    await expect(page.getByText('Tell us your name.')).toBeVisible();
+  });
+});

package/template/generated/netjes.ts

@@ -1,8 +1,19 @@
 // Generated by Netjes from the app's C# types and page files. Do not edit: the app rewrites it when it starts in
 // Development, and `netjes generate` writes it for CI (`netjes generate --check` fails when it is out of date).
-import { buildHref, isRouteHref, serverAction, type SearchParamsInput } from 'netjes';
+import { buildEndpointUrl, buildHref, isRouteHref, serverAction, type SearchParamsInput } from 'netjes';
 import { z } from 'zod';
 
+/** Every page's URL pattern. */
+export const routePatterns = ["/", "/about"] as const;
+
+/** Whether a URL that comes from data (a CMS, shared props) is one of the app's pages or another site. */
+export function isHref(value: string): value is Href {
+  return isRouteHref(value, routePatterns);
+}
+
+/** Checks such a URL at the boundary: `<Link href={Href.parse(item.href)}>`. The schemas below use it for each C# `Netjes.Href`. */
+export const Href = z.custom<Href>((value) => typeof value === 'string' && isHref(value), 'Not a URL this app serves');
+
 export const HomeProps = z.object({
   message: z.string(),
   renderedAt: z.iso.datetime({ offset: true, local: true }),
@@ -29,6 +40,29 @@ export const sharedProps = SiteProps;
 /** JSON endpoints by method and route: what they accept and return. */
 export const api = {} as const;
 
+/**
+ * What the app's endpoints read from their URLs, by method and route as in `api`: the route values, then the
+ * query string values the handler binds. A JSON endpoint has a key for each of its methods except HEAD, and any
+ * other endpoint one for GET, if it answers GET.
+ */
+export type EndpointParams = Record<never, never>;
+export type EndpointKey = keyof EndpointParams;
+const endpointTemplates: Record<EndpointKey, string> = {};
+
+/**
+ * The URL of one of the app's endpoints, with its values encoded: `endpointUrl('GET /api/posts/{slug}/likes/', { slug })`.
+ * The values the route does not name go in the query string, followed by the third argument. The URL has no base
+ * path: pass it through `useHref` for a `fetch` or an `<a href>`.
+ */
+export function endpointUrl<K extends EndpointKey>(
+  key: K,
+  ...args: {} extends EndpointParams[K]
+    ? [params?: EndpointParams[K], search?: SearchParamsInput]
+    : [params: EndpointParams[K], search?: SearchParamsInput]
+): string {
+  return buildEndpointUrl(endpointTemplates[key], args[0] ?? {}, args[1], key);
+}
+
 /** Form fields of page actions (`MapPageAction`), by page pattern. */
 export const forms = {} as const;
 
@@ -48,23 +82,18 @@ export type Route = '/' | '/about';
 /** What `<Link href>` and `router.push` accept: the app's routes, with a query or fragment, or another site. */
 export type Href = Route | `${Route}?${string}` | `${Route}#${string}` | `?${string}` | `#${string}` | `http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}`;
 
-/** The URL of a page, with its parameters encoded: `route('/blog/[slug]', { slug })`. */
+/**
+ * The URL of a page, with its parameters encoded: `route('/blog/[slug]', { slug })`. The third argument is the
+ * query, and `{ hash }` in the fourth adds a fragment: `route('/docs/[...path]', { path }, undefined, { hash: 'keys' })`.
+ */
 export function route<P extends RoutePattern>(
   pattern: P,
-  ...args: {} extends RouteParams[P] ? [params?: RouteParams[P], search?: SearchParamsInput] : [params: RouteParams[P], search?: SearchParamsInput]
+  ...args: {} extends RouteParams[P]
+    ? [params?: RouteParams[P], search?: SearchParamsInput, options?: { hash?: string | undefined }]
+    : [params: RouteParams[P], search?: SearchParamsInput, options?: { hash?: string | undefined }]
 ): Href {
-  return buildHref(pattern, args[0] ?? {}, args[1]) as Href;
+  return buildHref(pattern, args[0] ?? {}, args[1], args[2]) as Href;
 }
-/** Every page's URL pattern. */
-export const routePatterns = ["/", "/about"] as const;
-
-/** Whether a URL that comes from data (a CMS, shared props) is one of the app's pages or another site. */
-export function isHref(value: string): value is Href {
-  return isRouteHref(value, routePatterns);
-}
-
-/** Checks such a URL at the boundary: `<Link href={Href.parse(item.href)}>`. */
-export const Href = z.custom<Href>((value) => typeof value === 'string' && isHref(value), 'Not a URL this app serves');
 
 declare module 'netjes' {
   interface Register {

package/template/package.json

@@ -9,7 +9,8 @@
     "dev": "netjes dev",
     "build": "vite build && vite build --ssr",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:e2e": "dotnet build && playwright test",
+    "typecheck": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.node.json --noEmit",
     "generate": "netjes generate",
     "routes": "netjes routes"
   },
@@ -21,10 +22,12 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
     "@tailwindcss/vite": "^4.3.3",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",
+    "@types/node": "^22.20.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^30.1.3",

package/template/playwright.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Each project runs the app as its own ASP.NET Core process: one in Development (the Vite dev server) and one in
+// Production (the `npm run build` output). `npm run test:e2e` builds the .NET app first; install the browser once with
+// `npx playwright install chromium`. E2E_DEV_PORT, E2E_PROD_PORT and E2E_VITE_PORT move the ports, so that several runs
+// can share a machine. With CI set, Playwright always starts fresh servers; otherwise it reuses one that is listening.
+const DEV_URL = `http://127.0.0.1:${process.env['E2E_DEV_PORT'] ?? '5090'}`;
+const PROD_URL = `http://127.0.0.1:${process.env['E2E_PROD_PORT'] ?? '5091'}`;
+const VITE_PORT = process.env['E2E_VITE_PORT'] ?? '5190';
+
+export default defineConfig({
+  testDir: './e2e',
+  forbidOnly: !!process.env['CI'],
+  retries: process.env['CI'] ? 1 : 0,
+  use: { ...devices['Desktop Chrome'], trace: 'retain-on-failure' },
+  projects: [
+    { name: 'development', use: { baseURL: DEV_URL } },
+    { name: 'production', use: { baseURL: PROD_URL } },
+  ],
+  webServer: [
+    {
+      command: 'dotnet run --no-build --no-launch-profile',
+      url: `${DEV_URL}/healthz`,
+      env: { ASPNETCORE_ENVIRONMENT: 'Development', ASPNETCORE_URLS: DEV_URL, Netjes__ViteDevPort: VITE_PORT },
+      reuseExistingServer: !process.env['CI'],
+      timeout: 120_000,
+    },
+    {
+      command: 'npm run build && dotnet run --no-build --no-launch-profile',
+      url: `${PROD_URL}/healthz`,
+      env: { ASPNETCORE_ENVIRONMENT: 'Production', ASPNETCORE_URLS: PROD_URL },
+      reuseExistingServer: !process.env['CI'],
+      timeout: 180_000,
+    },
+  ],
+});

package/template/tests/__NAME__.Tests/AppFactory.cs

@@ -0,0 +1,31 @@
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Microsoft.Extensions.DependencyInjection;
+using Netjes.Rendering;
+
+namespace __NAME__.Tests;
+
+/// <summary>Runs the real app in memory, with its pipeline and services, and without a client build or Node.</summary>
+public sealed class AppFactory : WebApplicationFactory<Program>
+{
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        // Not Development: there Netjes output-caches no page, so a test of CachePage would see every request render.
+        builder.UseEnvironment("Testing");
+        // Development mode reads the routes from app/ on disk; nothing is rendered, so no Vite or Node is needed.
+        builder.UseSetting("Netjes:Mode", "Development");
+        builder.ConfigureServices(services =>
+        {
+            services.AddSingleton<ISsrRenderer, FixedHtml>();
+            // Development mode would rewrite generated/netjes.ts: a test run leaves it as it is, for `netjes generate --check`.
+            services.Configure<NetjesOptions>(options => options.TypesFile = null);
+        });
+    }
+
+    /// <summary>Stands in for the Node process: a document request gets this HTML. A payload request goes through no renderer.</summary>
+    private sealed class FixedHtml : ISsrRenderer
+    {
+        public Task<string> RenderAsync(string payloadJson, CancellationToken cancellationToken) =>
+            Task.FromResult("<!DOCTYPE html><html><body>rendered</body></html>");
+    }
+}

package/template/tests/__NAME__.Tests/HomePageTests.cs

@@ -0,0 +1,55 @@
+using System.Net;
+using System.Text.Json.Nodes;
+
+namespace __NAME__.Tests;
+
+/// <summary>The home page's loader and server action (Features/Home/HomePage.cs), requested as the client router does.</summary>
+public sealed class HomePageTests(AppFactory app) : IClassFixture<AppFactory>
+{
+    [Fact]
+    public async ValueTask TheHomePage_HasTheLoadersMessage()
+    {
+        var client = app.CreateClient();
+        client.DefaultRequestHeaders.Add(NetjesHeaders.Data, "1");
+
+        var response = await client.GetAsync("/", TestContext.Current.CancellationToken);
+        var payload = JsonNode.Parse(await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken))!;
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.Equal("Hello from C#", (string?)payload["props"]!["message"]);
+    }
+
+    [Fact]
+    public async ValueTask Greeting_WithoutAName_IsAFieldError()
+    {
+        var (status, result) = await Greet("");
+
+        Assert.Equal(HttpStatusCode.UnprocessableEntity, status);
+        Assert.Equal("Tell us your name.", (string?)result["errors"]!["name"]![0]);
+    }
+
+    [Fact]
+    public async ValueTask Greeting_WithAName_SaysHello()
+    {
+        var (status, result) = await Greet("Ada");
+
+        Assert.Equal(HttpStatusCode.OK, status);
+        Assert.Equal("Hello, Ada!", (string?)result["result"]!["text"]);
+    }
+
+    /// <summary>Posts the form with an antiforgery token: the header takes the token, the client's cookies its cookie.</summary>
+    private async Task<(HttpStatusCode, JsonNode)> Greet(string name)
+    {
+        var client = app.CreateClient();
+        var token = JsonNode.Parse(await client.GetStringAsync("/_netjes/antiforgery", TestContext.Current.CancellationToken))!;
+        client.DefaultRequestHeaders.Add(NetjesHeaders.Data, "1");
+        client.DefaultRequestHeaders.Add((string)token["headerName"]!, (string)token["requestToken"]!);
+
+        var response = await client.PostAsync(
+            "/_netjes/actions/home.greet",
+            new FormUrlEncodedContent([new("name", name)]),
+            TestContext.Current.CancellationToken);
+
+        return (response.StatusCode, JsonNode.Parse(await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken))!);
+    }
+}

package/template/tests/__NAME__.Tests/__NAME__.Tests.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <IsPackable>false</IsPackable>
+    <OutputType>Exe</OutputType>
+  </PropertyGroup>
+
+  <!-- xunit.v3.mtp-off is xUnit v3 for dotnet test's default runner, VSTest, which works in any folder. In a repository
+       whose global.json selects Microsoft.Testing.Platform as the test runner, reference xunit.v3 in its place. -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.14" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.11.0" />
+    <PackageReference Include="xunit.v3.mtp-off" Version="4.0.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="4.0.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../__NAME__.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Netjes" />
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+</Project>

package/template/tsconfig.app.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", "**/bin", "**/obj", "publish", "out", "e2e", "scripts", "vite.config.ts", "playwright.config.ts"]
+}

package/template/tsconfig.json

@@ -1,19 +1,4 @@
 {
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2023", "DOM", "DOM.Iterable"],
-    "types": ["vite/client"],
-    "jsx": "react-jsx",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    "allowImportingTsExtensions": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["app", "components", "generated", "vite.config.ts"]
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
 }

package/template/tsconfig.node.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.app.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts", "playwright.config.ts", "e2e", "scripts"],
+  "exclude": ["node_modules"]
+}