Web app conventions
Server-side fetching, Server Actions, caching rules and the embeddable widget.
On this page
ikazebot-web is Next.js 16 with cacheComponents: true, React 19 with the React Compiler, Tailwind 4 and shadcn on Base UI. It holds the dashboard, the public site and these docs, the widget iframe and help page, and the standalone embed.js.
Route groups
| Group | What | Notes |
|---|---|---|
(marketing) | Landing, features, pricing, legal, docs | Static: no session read, prerendered |
(auth) | Sign-in, sign-up, onboarding, invitations, password reset | Signed-out frame |
(dashboard) | Everything signed-in | requireAuth() first |
widget/[agentId], help/[agentId] | The chat inside the iframe, and the hosted help page | No session cookie, no workspace chrome |
Data in: serverFetch
All data goes through serverFetch. Never call fetch directly. It enforces the base URL, a 15-second timeout, the shared error contract and a required response schema:
const agents = await serverFetch('/api/agents', {
schema: agentListSchema, // z.void() for an empty response
forwardSession: true, // authenticated: request-specific, never cached
});
The browser never calls the API itself. Pages fetch in Server Components, and API_BASE_URL has no NEXT_PUBLIC_ prefix.
Data out: Server Actions returning ActionResult<T>
Mutations are Server Actions. They never throw across the server/client boundary, because a thrown error arrives as an opaque digest with no message. Failure is a value:
export async function renameAgentAction(id: string, name: string): Promise<ActionResult<Agent>> {
try {
const agent = await serverFetch(`/api/agents/${id}`, { method: 'PATCH', body: { name }, schema: agentSchema, forwardSession: true });
updateTag(`agent:${id}`); // the user must see their own write at once
return { ok: true, data: agent };
} catch (error) {
return actionFailedFrom(error); // replaces an unexpected message rather than forwarding it
}
}
The caller narrows on ok. Forms use React Hook Form with the local zod-resolver, not @hookform/resolvers.
Auth on every protected page
requireAuth() is the first statement of every protected page. It redirects rather than returning null, so forgetting to check the result cannot render a page for an anonymous visitor. requireAdmin() is for role-gated pages, but it only affects rendering; it is never the security boundary, and the API enforces the same rule again.
cacheComponents changes the rules
- Reading request data (
cookies(),headers(),searchParams) or doing uncached I/O outside a<Suspense>boundary is a build error, not a silently dynamic page. forwardSession: truemakes a read request-specific, so a'use cache'function may not forward a session. That is the guard against serving one visitor's session to another.- Invalidation: use
updateTag(tag)when the user must see their own write immediately, andrevalidateTag(tag, profile)with an explicitcacheLifefor stale-while-revalidate. The one-argumentrevalidateTagis deprecated. params,searchParams,cookies()andheaders()are async; await them.- Request interception lives in
proxy.ts(renamed frommiddleware.tsin Next 16).
Components
Server Components by default. Use 'use client' only where interactivity requires it, and as far down the tree as possible. The React Compiler memoises, so do not hand-write useMemo or useCallback to work around it.
Environment
Server-only variables have no NEXT_PUBLIC_ prefix and are parsed lazily in lib/env.ts, because a module-level parse would make next build demand runtime values. NEXT_PUBLIC_ means in the client bundle and public; treat it as a disclosure.
The widget is not a page
embed/embed.ts compiles to public/embed.js: a standalone script of a few kilobytes with no React. The build checks its size budget (scripts/check-embed-size.mjs). Its only jobs are to draw the bubble, open an iframe, and relay the ikazebot(...) command API over postMessage.
- 1Customer page loads embed.js
- 2Fetch widget configallowed domains, exposure
- 3Draw bubblein a closed shadow root
- 4Open → iframe /widget/[agentId]
- 5postMessage relayorigin-checked both ways
The rules it keeps: one global, styles inside a closed shadow root, messages accepted only from our iframe's origin, async so it never blocks the page, and loading twice runs it once.
These docs
Docs pages are Markdown in content/docs/<section>/<slug>.md, listed in src/lib/docs.ts (one registry for the sidebar, the index, the static routes and previous/next). A fenced flow block draws a step diagram. When a feature ships or changes, its docs page changes in the same pull request, and only shipped behaviour is documented.