building-app-routes

Write the logic as a create<Name>Handler factory in src/server/handlers/ returning (request: Request) => Promise<Response>, wire it in src/server/composition.ts, then re-export it as a one-line POST export from src/app/api/<name>/route.ts.

Place "use client" on the smallest file that owns state, effects, browser APIs, or DOM event handlers, and pass data down as props from Server Components. Never put it on a layout, since that moves the entire subtree into the client bundle.

Yes, when the handler is written as a Web-standard function taking a Request and returning a Response with no next imports. Tests drive it with a plain new Request(...) and assert on the Response, as the repository's server tests do.

Centralizing process.env reads in src/server/env.ts makes configuration auditable in one file and prevents secrets from leaking into client bundles. Other modules receive values as arguments wired through the composition root.

Next.js inlines NEXT_PUBLIC_ variables into the client bundle at build time, so the value is published to every user and frozen until a rebuild. Never prefix credentials, and prefer constants or props for genuinely public values.

Unit tests never render the App Router tree and typecheck does not resolve "use client", the server-only marker, or route export shapes. Only pnpm build validates those constraints, and opening the page confirms the request actually reaches it.