Build a Next.js Backend

Next.js is the backend here: Server Components read, Server Actions write, route handlers serve webhooks and external clients. The rule that organizes everything: authorization lives next to the data, in a server-only layer, and runs on every call. Pages, actions and proxy.ts do not carry it.

1. Audit current state

Read .claude/stack-profile.md (frontend.meta: next, backend.track, database, hosting). Then:

grep -n '"next"\|"react"\|"typescript"' package.json; ls middleware.ts src/middleware.ts proxy.ts src/proxy.ts 2>/dev/null
grep -n "cacheComponents\|partialPrefetching\|allowedOrigins" next.config.*
grep -rln "'use server'\|\"use server\"" src | xargs -I{} sh -c 'echo "== {}"; grep -c "getViewer\|requireViewer\|auth()" {}'   # actions with 0 = no auth check
grep -rn "process.env" src --include=*.ts --include=*.tsx | grep -v "src/libs/env\|src/server/env"                  # raw env reads
grep -rn "from '@supabase/supabase-js'\|createClient(" src | grep -v "src/libs/supabase"                           # clients outside the seam
grep -rLn "server-only" src/server 2>/dev/null; ls src/server src/features/*/actions.ts 2>/dev/null
grep -rn "export const \(dynamic\|revalidate\|fetchCache\|runtime\)" src/app                                      # segment configs

Findings to report: middleware.ts (renamed proxy.ts in 16), actions without an auth check, DB or SDK access inside components, whole DB rows passed to client components, raw process.env, revalidateTag(tag) with one argument.

2. Decide what to do

• No DAL (data calls in pages or components) → create src/server/ (steps 5–6) and move calls one route at a time.
• Actions exist without validation or an auth check → step 5 "actions" first; it is the exposed surface.
• Next ≤ 15 → upgrade first (proxy.ts is never called on 15; Node 20.9+, TypeScript 5.1+).
• Everything present, pnpm build passes → "already in place".

3. Detect the data source and caching model

Versions: stack-versions.md.

4. Install only what's missing

pnpm add server-only zod        # server-only: Next resolves it itself; install it so lint and tools see it

For Supabase: set-up-supabase and set-up-nextjs-supabase-auth provide src/libs/supabase/* and src/server/auth.ts (getViewer, requireViewer).

5. Generate the seams

Layout (matches the folder standard): src/server/ server-only code, src/features/<domain>/actions.ts thin 'use server' files, src/app/ routing files only.

src/server/env.ts            # secrets, server-only
src/libs/env.client.ts       # NEXT_PUBLIC_* only
src/server/auth.ts           # getViewer / requireViewer
src/server/data/<domain>.ts  # DAL: authorize, query, return DTOs
src/features/<domain>/actions.ts
src/app/api/webhooks/<provider>/route.ts

Env — parse once, fail at boot. Client values are read as literal process.env.NEXT_PUBLIC_X (Next inlines only literal reads); server secrets live in a server-only module. Code: nextjs-backend-patterns.md, "Env".

DAL — every exported function authorizes first and returns a DTO, never a raw row:

// src/server/data/notes.ts
import 'server-only';
import { notFound } from 'next/navigation';
import { createClient } from '@/libs/supabase/server';
import type { Tables } from '@/libs/supabase/database.types';
import { requireViewer } from '@/server/auth';

export type NoteDTO = { id: string; body: string; createdAt: string };

const toDTO = (row: Pick<Tables<'notes'>, 'id' | 'body' | 'created_at'>): NoteDTO => ({
  id: row.id, body: row.body, createdAt: row.created_at,
});

export async function getNote(id: string): Promise<NoteDTO> {
  await requireViewer();
  const supabase = await createClient();
  const { data, error } = await supabase.from('notes').select('id, body, created_at').eq('id', id).maybeSingle();
  if (error) throw new Error(`getNote failed: ${error.code}`);
  if (!data) notFound(); // RLS hides other users' rows: "not yours" and "not there" look the same
  return toDTO(data);
}

Server Action — a public POST endpoint. Authenticate, validate, authorize (the DAL does), act, return a typed result:

// src/features/notes/actions.ts
'use server';
import { refresh } from 'next/cache';
import { unstable_rethrow } from 'next/navigation';
import { z } from 'zod';
import type { ActionResult } from '@/libs/action-result';
import { getViewer } from '@/server/auth';
import { createNote, type NoteDTO } from '@/server/data/notes';

const CreateNote = z.object({ body: z.string().trim().min(1).max(2000) });

export async function createNoteAction(_previous: ActionResult<NoteDTO> | null, formData: FormData): Promise<ActionResult<NoteDTO>> {
  if (!(await getViewer())) return { ok: false, code: 'unauthenticated' };
  const parsed = CreateNote.safeParse({ body: formData.get('body') });
  if (!parsed.success) return { ok: false, code: 'invalid', fieldErrors: z.flattenError(parsed.error).fieldErrors };
  try {
    const note = await createNote(parsed.data);
    refresh(); // per-user data is not cached on the server; re-render the current route
    return { ok: true, data: note };
  } catch (error) {
    unstable_rethrow(error); // let redirect() and notFound() through
    return { ok: false, code: 'failed' };
  }
}

ActionResult (src/libs/action-result.ts), the form component with useActionState, the webhook route handler, and the error boundaries: nextjs-backend-patterns.md.

6. Wire

• next.config.ts: cacheComponents: true, partialPrefetching: true for new code; add experimental.serverActions.allowedOrigins only when a reverse proxy forwards a different host; raise bodySizeLimit (default 1 MB) only for upload actions.
• src/proxy.ts (same level as app/): session refresh and coarse redirects only; Node runtime; no data fetching (set-up-nextjs-supabase-auth). Rename middleware.ts to proxy.ts and the export to proxy.
• Pages that read request data (cookies(), headers(), searchParams, params) wrap that component in <Suspense>; the DAL's getViewer() reads cookies, so the same applies.
• Self-hosting several instances: set NEXT_SERVER_ACTIONS_ENCRYPTION_KEY (openssl rand -base64 32) so every instance shares one key.
• CI: next build prerenders cached pages, so a page reading Supabase through 'use cache' needs the API reachable at build (the local stack in CI, or the staging project).

7. Verify

typecheck is tsc --noEmit in a Next.js app (one tsconfig); add "typecheck": "tsc --noEmit" to package.json if it is missing.

pnpm typecheck
pnpm build                       # Cache Components errors name the exact uncached read or missing <Suspense>
pnpm build && grep -rEl "sb_secret_|SUPABASE_SECRET_KEY" .next/static   # prints nothing

Then four checks by hand or test: an anonymous request to a protected route redirects; calling a DAL function with no session redirects or throws; a webhook with a bad signature returns 400 and with a good one 200; importing @/libs/supabase/admin from a 'use client' file fails the build.

References

• nextjs-backend-patterns.md — DAL, actions, route handlers, env, errors, proxy rules with code.
• nextjs-caching-patterns.md — Cache Components: use cache, cacheLife, cacheTag, updateTag, revalidateTag.
• ../../frontend/_shared/framework-idioms.md — React 19 idioms the client side follows.
• ../../core/_shared/security-baseline.md — rules 3 and 4.