Every write in Nakodo goes through a Server Action. There are no API routes that accept a form, no fetch calls to our own endpoints from the browser, and no mutation that is not a function call with "use server" at the top of its file. After a year that adds up to a population worth counting, because a convention is only a convention if the files agree.
The population
$ grep -rl '"use server"' src src/app/(app)/campaigns/actions.ts 31 actions, 1,372 lines src/app/(app)/settings/actions.ts 9 actions, 288 lines src/app/(app)/support/actions.ts 6 actions, 258 lines src/app/admin/users/actions.ts 5 actions, 178 lines src/app/(auth)/actions.ts 5 actions, 197 lines src/app/admin/support/actions.ts 2 actions, 78 lines src/app/(app)/actions.ts 1 action, 31 lines src/app/admin/mailing/actions.ts 1 action, 205 lines src/app/unsubscribe/actions.ts 1 action, 23 lines src/app/o/[token]/actions.ts 1 action, 11 lines 62 actions, 2,641 lines of action code, a median of 29 lines each. The longest is 192 lines (writing fit notes, which touches three tables); the shortest is 5 (recording an opt-out).
They all return the same thing
| Return type | Actions |
|---|---|
Promise<ActionResult> | 38 |
Promise<ActionResult<T>> | 13 |
Promise<AuthState> | 5 |
Promise<void> | 3 |
Promise<PlanChangeResult> | 2 |
Promise<SendResult> | 1 |
51 of 62 return the same discriminated union, and every one of the 62 has an explicit return annotation. The type is 20 lines in src/lib/action.ts:
export type ActionOk<T extends object = object> = { ok: true; message?: string; upgrade?: boolean; error?: undefined; values?: undefined; } & T; export type ActionFailure = { ok: false; error: string; upgrade?: boolean; values?: Record<string, string>; message?: undefined; }; export type ActionResult<T extends object = object> = ActionOk<T> | ActionFailure; The error?: undefined and message?: undefined members are the load-bearing part. Without them TypeScript lets you read r.error on a success and get undefined, which compiles and then quietly never shows the user anything. With them, every caller has to narrow on r.ok first.
Two optional fields earn their place. values echoes submitted text back, so a failed submit does not clear the form. upgrade marks a failure as a plan limit rather than a mistake, so the UI can render the message next to a link to the plans instead of a generic apology.
The four helpers that make them look alike
export const fail = (error: string, extra?) => ({ ok: false, error, ...extra }); export function failure(e: unknown, { context, fallback = GENERIC } = {}): ActionFailure { unstable_rethrow(e); if (e instanceof LimitError) return { ok: false, error: e.message, upgrade: true }; if (e instanceof UserError) return { ok: false, error: e.message }; console.error(context ?? "", e); return { ok: false, error: fallback }; } export const formText = <K extends string>(form: FormData, ...names: K[]) => Object.fromEntries(names.map((n) => [n, String(form.get(n) ?? "").trim()])); export async function tooFast(rule: RateLimitRule, userId: string): Promise<ActionFailure | null>; failure is the one I would keep if I could only keep one. unstable_rethrow goes first because Next signals redirects and 404s by throwing, and a catch that swallows those turns a redirect into a silent no-op. Then two error classes are allowed through as written text, because their messages were written for users, and everything else is logged and replaced with one sentence. That is how 72,683 lines of app code manage to have no stack trace reach a page and no console.log outside the scripts folder.
What the 62 actually do
| Trait | Actions with it |
|---|---|
an auth gate (requireUser, requireCampaign, requireThread, requireAdmin) | 55 |
try/catch | 50 |
fail or failure | 52 |
tooFast per-user rate limit | 41 |
| writes an audit row | 36 |
| validates input with zod | 35 |
calls revalidatePath (46 calls in total) | 38 |
takes FormData | 17 |
| takes typed arguments | 45 |
redirect | 9 |
after() for work past the response | 6 |
| a plan-limit assertion | 5 |
| a Postgres advisory lock | 1 |
Which makes the median action look like this, start to finish:
export async function saveProfileAction(_: unknown, form: FormData): Promise<ActionResult> { const user = await requireUser(); const slow = await tooFast("write", user.id); if (slow) return slow; const parsed = profileInput.safeParse(formText(form, "fullName", "companyName")); if (!parsed.success) return fail("One of the fields is too long."); try { await db.insert(profiles).values({ id: user.id, ...values }) .onConflictDoUpdate({ target: profiles.id, set: values }); } catch (e) { return failure(e); } await audit({ action: "profile.updated", userId: user.id, entityType: "user", entityId: user.id }); revalidatePath("/settings"); return { ok: true, message: "Noted." }; } Identify, limit, validate, write, audit, revalidate, answer. Seven steps, always in that order, and the order matters in two places: the rate limit is checked before any parsing so a flood costs nothing, and the audit row is written before the revalidate so a crash cannot leave a changed row with no record of who changed it.
The seven without an auth check
optOutAction resubscribeAction signIn signUp resendConfirmation requestPasswordReset resetPassword Five are the authentication actions themselves: there is nobody to require yet. The other two are reached from a link in an email by somebody who, by definition, cannot sign in to use them. They authorise on a token in the URL instead, which is why the opt-out action is the shortest in the codebase: the page that calls it has already resolved the token.
That split is worth stating out loud as a rule, because "55 of 62 check" sounds like a gap in an audit and is actually the whole design: an action either requires a session or it requires a secret, and there is no third option.
Two things I am changing
The 27 actions with no zod schema. Most of them take no input at all, or one id that an auth helper immediately uses to load a row (if the id is wrong, the load 404s, which is the check). But grep cannot tell those apart from the ones that take a boolean and trust it, and I had to read all 27 to be sure. The fix is not more schemas, it is a convention: an action whose arguments are already proven by the row it loads gets a one-line comment saying so.
The 1,372-line campaigns file. 31 of the 62 actions live in it, which is 50% of the mutations in the app in one module, and it is the largest file in the repo. The actions themselves are fine, at a median of 29 lines; the file is simply a bucket. Splitting it by screen (results, brief, outreach, proposal) is a mechanical change that would make the next audit of this kind readable without a script.
One consequence is visible from outside. Not one of the 62 is reachable from a public page: every button on the pricing page and how it works is a link, the only forms on the public site are sign-in and sign-up, and that is part of why 74 of the 76 public pages are prerendered, the other two being dynamic only because they read a header to pick a currency. The mutations start at the login boundary and stay behind it.

