netjes 0.0.0-stage → 0.0.2

package/src/vitals.tsx

@@ -0,0 +1,68 @@
+// netjes/vitals: Core Web Vitals, measured with the web-vitals package (an optional peer dependency of netjes).
+import { useContext, useEffect, useRef } from 'react';
+import { type Metric, onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals';
+import { usePagePayload } from './router.tsx';
+import { VitalsEndpointContext } from './vitals-config.ts';
+
+/** One measurement, as `web-vitals` reports it, with the route pattern of the page it was measured on. */
+export type WebVitalsMetric = Pick<Metric, 'name' | 'value' | 'rating' | 'delta' | 'id' | 'navigationType'> & {
+  route: string | null;
+};
+
+type Subscriber = (metric: WebVitalsMetric) => void;
+
+const subscribers = new Set<Subscriber>();
+const reported: WebVitalsMetric[] = [];
+let started = false;
+
+/** Web vitals describe the page load, so they are measured once, for the route the document was loaded on. */
+function start(route: string | null) {
+  if (started) return;
+  started = true;
+  const report = ({ name, value, rating, delta, id, navigationType }: Metric) => {
+    const metric: WebVitalsMetric = { name, value, rating, delta, id, navigationType, route };
+    reported.push(metric);
+    for (const subscriber of subscribers) subscriber(metric);
+  };
+  onCLS(report);
+  onFCP(report);
+  onINP(report);
+  onLCP(report);
+  onTTFB(report);
+}
+
+/** Like Next.js's `useReportWebVitals`: calls back with each Core Web Vital of this page load (also ones measured earlier). */
+export function useReportWebVitals(callback: (metric: WebVitalsMetric) => void) {
+  const { route } = usePagePayload();
+  const latest = useRef(callback);
+  latest.current = callback;
+
+  useEffect(() => {
+    const subscriber: Subscriber = (metric) => latest.current(metric);
+    for (const metric of reported) subscriber(metric);
+    subscribers.add(subscriber);
+    start(route);
+    return () => {
+      subscribers.delete(subscriber);
+    };
+    // Subscribes once; the route is the one the page was loaded on.
+  }, []);
+}
+
+/** The measurements a `<WebVitals />` has sent, so one that mounts again does not send the replayed ones twice. */
+const sent = new WeakSet<WebVitalsMetric>();
+
+/**
+ * Sends Core Web Vitals to the server, which records them as `netjes.web_vitals.*` histograms (turn on
+ * `NetjesOptions.CollectWebVitals`). Render it once, e.g. in the root layout.
+ */
+export function WebVitals() {
+  const endpoint = useContext(VitalsEndpointContext);
+  useReportWebVitals((metric) => {
+    if (!endpoint || sent.has(metric)) return;
+    sent.add(metric);
+    const { name, value, rating, route, navigationType } = metric;
+    navigator.sendBeacon(endpoint, JSON.stringify({ name, value, rating, route, navigationType }));
+  });
+  return null;
+}

package/src/zod.ts

@@ -0,0 +1,72 @@
+// zod helpers (netjes/zod). Only this module imports zod, so apps on another schema library do not need it.
+import { z } from 'zod';
+
+/**
+ * What `deferred()` parses to: a thenable that React's `use()` reads (it records `status` and `value` as React
+ * expects). Not a Promise, because zod would then treat the whole schema as async.
+ */
+export class DeferredValue<T> implements PromiseLike<T> {
+  status: 'pending' | 'fulfilled' | 'rejected' = 'pending';
+  value?: T;
+  reason?: unknown;
+  private readonly settled: Promise<T>;
+
+  constructor(source: PromiseLike<unknown>, parse: (value: unknown) => T) {
+    this.settled = Promise.resolve(source).then(
+      (raw) => {
+        try {
+          const value = parse(raw);
+          this.status = 'fulfilled';
+          this.value = value;
+          return value;
+        } catch (error) {
+          this.status = 'rejected';
+          this.reason = error;
+          throw error;
+        }
+      },
+      (reason) => {
+        this.status = 'rejected';
+        this.reason = reason;
+        throw reason;
+      },
+    );
+    // Values nobody reads must not surface as unhandled rejections.
+    this.settled.catch(() => {});
+  }
+
+  then<R1 = T, R2 = never>(
+    onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
+    onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): PromiseLike<R1 | R2> {
+    return this.settled.then(onFulfilled, onRejected);
+  }
+}
+
+const validated = new WeakMap<object, Map<z.ZodType, DeferredValue<unknown>>>();
+
+/**
+ * A `Page.Defer` value in page or layout props: a promise of `schema`'s output. Read it with React's `use()` inside
+ * a Suspense boundary. The resolved value is validated; a mismatch rejects (and reaches the error boundary).
+ */
+export function deferred<Schema extends z.ZodType>(schema: Schema): z.ZodType<PromiseLike<z.output<Schema>>, Promise<unknown>> {
+  const parsed = z
+    .custom<Promise<unknown>>((value) => value instanceof Promise, { message: 'Expected a deferred value (Page.Defer)' })
+    .transform((promise): DeferredValue<z.output<Schema>> => {
+      // The same thenable every time, so use() does not suspend again after each render.
+      let bySchema = validated.get(promise);
+      if (!bySchema) validated.set(promise, (bySchema = new Map()));
+      let result = bySchema.get(schema);
+      if (!result) {
+        result = new DeferredValue(promise, (value) => {
+          const parsed = schema.safeParse(value);
+          if (parsed.success) return parsed.data;
+          throw new Error(`Invalid deferred value: ${parsed.error.issues.map((i) => `${i.path.join('.') || '(value)'}: ${i.message}`).join('; ')}`);
+        });
+        bySchema.set(schema, result);
+      }
+      return result as DeferredValue<z.output<Schema>>;
+    });
+  // zod types a transform returning a thenable as its awaited value; it is the thenable.
+  return parsed as unknown as z.ZodType<PromiseLike<z.output<Schema>>, Promise<unknown>>;
+}

package/template/.dockerignore

@@ -0,0 +1,11 @@
+**/node_modules
+**/bin
+**/obj
+publish
+**/dist
+**/.vite
+**/test-results
+.git
+**/.env
+**/.env.*
+!**/.env.example

package/template/Dockerfile

@@ -0,0 +1,58 @@
+# syntax=docker/dockerfile:1
+#   docker compose up                                                    -> dev (dotnet watch + Vite HMR)
+#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up   -> production image
+# Builds against the published Netjes NuGet and npm packages, as any app made by `npx netjes new` does. Only an app
+# scaffolded from a Netjes checkout references the checkout, which this build cannot see: scaffold it with --packages.
+ARG NODE_IMAGE=node:24.22.1-bookworm-slim
+ARG SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0.403-noble
+ARG RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0.14-noble
+
+FROM ${NODE_IMAGE} AS node
+
+# npm dependencies, cached until package.json or the lockfile changes.
+FROM node AS deps
+WORKDIR /src
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Development: the source is bind-mounted by docker-compose.override.yml.
+FROM ${SDK_IMAGE} AS dev
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+ && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+WORKDIR /src
+COPY --from=deps /src ./
+ENV ASPNETCORE_ENVIRONMENT=Development \
+    ASPNETCORE_URLS=http://+:8080 \
+    DOTNET_USE_POLLING_FILE_WATCHER=1 \
+    DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH=1 \
+    NETJES_VITE_HOST=0.0.0.0
+EXPOSE 8080 5173
+CMD ["dotnet", "watch", "run", "--no-launch-profile"]
+
+# Client bundle (dist/client) and server bundle + sidecar (dist/server).
+FROM deps AS client
+COPY . .
+RUN npm run build
+
+FROM ${SDK_IMAGE} AS build
+WORKDIR /src
+COPY __NAME__.csproj ./
+RUN dotnet restore
+COPY . .
+COPY --from=client /src/dist dist
+RUN dotnet publish -c Release -o /app --no-restore -p:NetjesSkipClientBuild=true
+
+# Production: ASP.NET Core runtime plus the node binary for the SSR sidecar. Runs as the non-root app user.
+FROM ${RUNTIME_IMAGE} AS production
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+# Where ASP.NET Core keeps its Data Protection keys; docker-compose.prod.yml mounts a volume here.
+RUN mkdir -p /home/app/.aspnet/DataProtection-Keys && chown -R app:app /home/app/.aspnet
+WORKDIR /app
+COPY --from=build /app ./
+USER $APP_UID
+EXPOSE 8080
+HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:8080/healthz').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
+ENTRYPOINT ["dotnet", "__NAME__.dll"]

package/template/Features/Home/HomePage.cs

@@ -0,0 +1,32 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace __NAME__.Features.Home;
+
+/// <summary>
+/// The home page's loader (the C# counterpart of getServerSideProps) and a server action. Their types are generated
+/// as zod schemas and typed references in generated/netjes.ts.
+/// </summary>
+public static class HomePage
+{
+    public sealed record HomeProps(string Message, DateTimeOffset RenderedAt);
+
+    // Form inputs have init properties: a field the post leaves out, such as an unchecked checkbox, keeps its default,
+    // where form binding would refuse the post for a positional record.
+    public sealed record GreetInput
+    {
+        public string? Name { get; init; }
+    }
+
+    public sealed record Greeting(string Text);
+
+    public static void MapHomePage(this IEndpointRouteBuilder app)
+    {
+        app.MapPageLoader("/", (TimeProvider time) => Page.Props(new HomeProps("Hello from C#", time.GetUtcNow())));
+
+        // Called from components/HelloForm.tsx through serverActions['home.greet'].
+        app.MapAction("home.greet", ([FromForm] GreetInput input) =>
+            string.IsNullOrWhiteSpace(input.Name)
+                ? ServerAction.Invalid("name", "Tell us your name.")
+                : ServerAction.Ok(new Greeting($"Hello, {input.Name.Trim()}!")));
+    }
+}

package/template/Program.cs

@@ -0,0 +1,28 @@
+using __NAME__;
+using __NAME__.Features.Home;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddNetjes(options =>
+    // Available in every page and layout through useSharedProps(sharedProps); typed in generated/netjes.ts.
+    options.UseSharedProps(_ => ValueTask.FromResult(new SiteProps("__TITLE__"))));
+builder.Services.AddHealthChecks().AddNetjes();
+
+var app = builder.Build();
+
+if (!app.Environment.IsDevelopment())
+{
+    // Once the site is served over https: HSTS on https responses, and http redirected to https. Behind a proxy
+    // that terminates TLS, add UseForwardedHeaders() first so the app sees the original scheme.
+    app.UseHsts();
+    app.UseHttpsRedirection();
+}
+
+app.UseNetjes();
+app.UseAntiforgery(); // after authentication, if you add it
+
+app.MapHealthChecks("/healthz");
+app.MapHomePage();
+app.MapPages(); // every other page file, plus the 404 fallback
+
+app.Run();

package/template/Properties/launchSettings.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:5080",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

package/template/README.md

@@ -0,0 +1,24 @@
+# __TITLE__
+
+A React app on ASP.NET Core, built with Netjes: Vite, Tailwind CSS, TanStack Query, zod and Vitest are set up.
+
+```bash
+npm run dev        # dotnet watch + Vite HMR, http://localhost:5080
+npm test           # Vitest component tests
+npm run typecheck
+npm run routes     # the route table, from C#
+npx netjes build   # types, client and server bundles
+npx netjes info    # check Node.js, the .NET SDK, the packages and this setup
+dotnet publish -c Release
+```
+
+- `app/` holds the pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `layout.tsx` wraps them all, `not-found.tsx` and `error.tsx` handle the rest.
+- `public/` is served at the site root. `public/favicon.svg`, which the metadata in `app/layout.tsx` links, is the Netjes mark: replace it with the app's own.
+- `Features/` holds the C# side, one folder per feature: `Features/Home/HomePage.cs` maps the home page's loader and the `home.greet` server action the form calls.
+- `AGENTS.md` tells coding agents how the app is laid out and what the rules are; `CLAUDE.md` imports it for Claude Code.
+- `Properties/launchSettings.json` holds the `http` launch profile that `dotnet run` and IDEs (F5) use: the app in Development on http://localhost:5080, as `npm run dev` runs it but without `dotnet watch`.
+- `generated/netjes.ts` holds zod schemas for what the loaders and actions return, typed server action references and typed routes. The app rewrites it when it starts in Development; commit it, and run `npx netjes generate --check` in CI.
+
+Outside Development, `Program.cs` sends HSTS on https responses and redirects http to https once the app knows its https port (`ASPNETCORE_HTTPS_PORT` or `ASPNETCORE_HTTPS_PORTS`). Behind a proxy that terminates TLS, add `UseForwardedHeaders()` (trusting only that proxy) so proxied requests count as https and get HSTS, and let the proxy redirect plain http. Netjes adds `X-Content-Type-Options`, `Referrer-Policy` and `X-Frame-Options: SAMEORIGIN` to every page; see `NetjesOptions.SecurityHeaders` to change that.
+
+With Docker: `docker compose up` for development, `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d` for production. In Development `appsettings.Development.json` limits `AllowedHosts` to loopback names (a DNS-rebinding guard); add a name there if you reach the dev app by another host. The Docker build restores Netjes from NuGet and npm, which is how any app made by `npx netjes new` references it. Only an app scaffolded from a Netjes checkout references the checkout instead; scaffold it with `netjes new --packages` to build it in Docker.

package/template/SiteProps.cs

@@ -0,0 +1,4 @@
+namespace __NAME__;
+
+/// <summary>The shared props every page and layout gets.</summary>
+public sealed record SiteProps(string SiteName);

package/template/_AGENTS.md

@@ -0,0 +1,64 @@
+# __TITLE__
+
+How this app is built, for coding agents and the people working with them. It is a [Netjes](https://github.com/DennisVerhoeven/netjes) app: ASP.NET Core receives every request and owns routing, data loading, server actions, authorization and caching; a Node sidecar renders the React pages; the browser hydrates them and navigates on the client.
+
+## Netjes docs
+
+- https://raw.githubusercontent.com/DennisVerhoeven/netjes/main/llms.txt: an index of the docs; https://raw.githubusercontent.com/DennisVerhoeven/netjes/main/llms-full.txt has the ones for building apps in one file. For people, the same docs are at https://github.com/DennisVerhoeven/netjes/blob/main/docs/README.md.
+- `.claude/skills/netjes/`: the conventions in short, with references for routing, data and actions, caching and streaming, testing and deployment. Read `SKILL.md` before changing pages, loaders or actions.
+- The docs on main can be ahead of the version this app uses (`npx netjes --version`). The installed package, with its types, is in `node_modules/netjes/`.
+
+## Layout
+
+| 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. |
+| `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. |
+| `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. |
+| `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. |
+
+## Commands
+
+```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
+dotnet build                # C#, warnings are errors
+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
+dotnet publish -c Release   # runs the build and ships dist/
+```
+
+## Adding a page with data
+
+1. Write the C# loader in `Features/<Feature>/`: a record for the props and `app.MapPageLoader("/blog/[slug]", (string slug, PostStore posts) => ...)` returning `Page.Props(new PostProps(...))`, `Page.NotFound()` or `Page.Redirect(url)`. Route parameters bind by name, like any minimal API.
+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.
+
+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.
+
+## Rules
+
+- 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.
+- 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.
+- 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.
+- Write the failing test first, then the change.
+
+## Before you finish
+
+```bash
+npm test && npm run typecheck && dotnet build && npx netjes generate --check
+```
+
+Then `npm run routes` should print no warnings, and the page should work in `npm run dev`, including with JavaScript turned off for forms.

package/template/_CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/__NAME__.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+<!--NETJES_REFERENCES-->
+</Project>

package/template/_gitattributes

@@ -0,0 +1,2 @@
+# The generator writes LF; keep it so on checkout, or `netjes generate --check` sees a difference.
+generated/** text eol=lf

package/template/_gitignore

@@ -0,0 +1,11 @@
+node_modules/
+bin/
+obj/
+/publish/
+dist/
+out/
+.vite/
+test-results/
+playwright-report/
+.env
+.env.*

package/template/app/about/page.tsx

@@ -0,0 +1,17 @@
+import type { Metadata } from 'netjes';
+
+export const metadata: Metadata = { title: 'About' };
+
+// No loader is mapped for this page, so it renders with empty props.
+export default function About() {
+  return (
+    <article className="space-y-4">
+      <h1 className="text-3xl font-bold tracking-tight">About</h1>
+      <p className="text-slate-600">
+        Pages are React components in <code>app/</code>, as in the Next.js App Router. ASP.NET Core routes every
+        request, runs the page's C# loader and renders the page on the server; after that, links navigate in the
+        browser, and forms call C# server actions.
+      </p>
+    </article>
+  );
+}

package/template/app/error.tsx

@@ -0,0 +1,15 @@
+import type { ErrorPageProps } from 'netjes';
+
+/** Errors below the root layout land here; the layout stays usable. */
+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>
+      <button type="button" onClick={reset} className="cursor-pointer rounded-full bg-slate-900 px-4 py-2 font-medium text-white">
+        Try again
+      </button>
+    </section>
+  );
+}

package/template/app/layout.tsx

@@ -0,0 +1,33 @@
+import { Link, type LayoutProps, type Metadata, useSharedProps } from 'netjes';
+import { sharedProps } from '../generated/netjes.ts';
+import '../styles/global.css';
+
+export const metadata: Metadata = {
+  title: { default: '__TITLE__', template: '%s · __TITLE__' },
+  icons: { icon: '/favicon.svg' },
+};
+
+const navLink = 'text-slate-500 no-underline hover:text-slate-900 aria-[current=page]:text-slate-900';
+
+/** The root layout: wraps every page and stays mounted across navigations. */
+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">
+      <header className="mb-12 flex items-baseline justify-between">
+        <Link href="/" className="text-xl font-semibold no-underline">
+          {site.siteName}
+        </Link>
+        <nav aria-label="Main" className="flex gap-5">
+          <Link href="/" className={navLink}>
+            Home
+          </Link>
+          <Link href="/about" className={navLink}>
+            About
+          </Link>
+        </nav>
+      </header>
+      <main>{children}</main>
+    </div>
+  );
+}

package/template/app/not-found.tsx

@@ -0,0 +1,14 @@
+import { Link, type Metadata, usePathname } from 'netjes';
+
+export const metadata: Metadata = { title: 'Not found' };
+
+export default function NotFound() {
+  return (
+    <section className="space-y-4">
+      <h1 className="text-3xl font-bold tracking-tight">Nothing at {usePathname()}</h1>
+      <Link href="/" className="underline">
+        Back to the home page
+      </Link>
+    </section>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,14 @@
+import { definePage } from 'netjes';
+import { Greeting } from '../components/Greeting.tsx';
+import { HelloForm } from '../components/HelloForm.tsx';
+import { pages } from '../generated/netjes.ts';
+
+// The props schema is generated from the C# HomeProps record (Features/Home/HomePage.cs).
+export default definePage(pages['/'], function Home({ message, renderedAt }) {
+  return (
+    <div className="space-y-12">
+      <Greeting message={message} renderedAt={renderedAt} />
+      <HelloForm />
+    </div>
+  );
+});

package/template/appsettings.Development.json

@@ -0,0 +1,3 @@
+{
+  "AllowedHosts": "localhost;127.0.0.1;[::1]"
+}

package/template/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

package/template/components/Greeting.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createTestApp } from 'netjes/testing';
+import { describe, expect, it } from 'vitest';
+import { Greeting } from './Greeting.tsx';
+
+describe('Greeting', () => {
+  it('shows the message from the loader and counts clicks', async () => {
+    render(<Greeting message="Hello" renderedAt="2026-10-28T12:00:00Z" />, { wrapper: createTestApp().Wrapper });
+
+    await userEvent.click(screen.getByRole('button', { name: 'Clicked 0 times' }));
+
+    expect(screen.getByRole('heading', { name: 'Hello' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Clicked 1 time' })).toBeDefined();
+  });
+
+  it('links to the about page without a full page load', async () => {
+    const app = createTestApp();
+    render(<Greeting message="Hello" renderedAt="2026-10-28T12:00:00Z" />, { wrapper: app.Wrapper });
+
+    await userEvent.click(screen.getByRole('link', { name: 'About this app' }));
+
+    expect(app.navigations).toEqual([{ type: 'push', href: '/about' }]);
+  });
+});

package/template/components/Greeting.tsx

@@ -0,0 +1,26 @@
+import { Link } from 'netjes';
+import { useState } from 'react';
+
+export function Greeting({ message, renderedAt }: { message: string; renderedAt: string }) {
+  const [clicks, setClicks] = useState(0);
+  return (
+    <section className="space-y-5">
+      <h1 className="text-4xl font-bold tracking-tight">{message}</h1>
+      <p className="text-slate-600">
+        Rendered by ASP.NET Core at <time dateTime={renderedAt}>{renderedAt}</time>.
+      </p>
+      <button
+        type="button"
+        onClick={() => setClicks((count) => count + 1)}
+        className="cursor-pointer rounded-full bg-slate-900 px-4 py-2 font-medium text-white hover:bg-slate-700"
+      >
+        Clicked {clicks} {clicks === 1 ? 'time' : 'times'}
+      </button>
+      <p>
+        <Link href="/about" className="underline">
+          About this app
+        </Link>
+      </p>
+    </section>
+  );
+}

package/template/components/HelloForm.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createTestApp } from 'netjes/testing';
+import { describe, expect, it } from 'vitest';
+import { HelloForm } from './HelloForm.tsx';
+
+describe('HelloForm', () => {
+  it('shows the greeting the server action returns', async () => {
+    const app = createTestApp({ actions: { 'home.greet': () => ({ ok: true, result: { text: 'Hello, Ada!' } }) } });
+    render(<HelloForm />, { wrapper: app.Wrapper });
+
+    await userEvent.type(screen.getByLabelText('Your name'), 'Ada');
+    await userEvent.click(screen.getByRole('button', { name: 'Say hello' }));
+
+    expect((await screen.findByRole('status')).textContent).toBe('Hello, Ada!');
+  });
+
+  it('shows the validation error from C# next to the field', async () => {
+    const app = createTestApp({ actions: { 'home.greet': () => ({ ok: false, status: 422, errors: { name: ['Tell us your name.'] } }) } });
+    render(<HelloForm />, { wrapper: app.Wrapper });
+
+    await userEvent.click(screen.getByRole('button', { name: 'Say hello' }));
+
+    expect(await screen.findByText('Tell us your name.')).toBeDefined();
+    expect(screen.getByLabelText('Your name').getAttribute('aria-invalid')).toBe('true');
+  });
+});