Skip to content

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

GroupWhatNotes
(marketing)Landing, features, pricing, legal, docsStatic: no session read, prerendered
(auth)Sign-in, sign-up, onboarding, invitations, password resetSigned-out frame
(dashboard)Everything signed-inrequireAuth() first
widget/[agentId], help/[agentId]The chat inside the iframe, and the hosted help pageNo 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:

ts
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:

ts
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: true makes 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, and revalidateTag(tag, profile) with an explicit cacheLife for stale-while-revalidate. The one-argument revalidateTag is deprecated.
  • params, searchParams, cookies() and headers() are async; await them.
  • Request interception lives in proxy.ts (renamed from middleware.ts in 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.

  1. 1Customer page loads embed.js
  2. 2Fetch widget configallowed domains, exposure
  3. 3Draw bubblein a closed shadow root
  4. 4Open → iframe /widget/[agentId]
  5. 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.

Get started free — 50 credits a month