server-actions-design

name	server-actions-design
description	Use when designing or reviewing Server Actions: the 'use server' directive contract, how a server-side function becomes invokable from the browser without an API route, form integration via the `action` attribute, the React 19 hooks useActionState / useFormStatus, progressive enhancement (works without JS), server-side validation and authorization as mandatory rather than optional, revalidation primitives (revalidatePath, revalidateTag, redirect), error handling and bound arguments, and the security boundary that makes Server Actions a public endpoint despite their function-like syntax. Covers Next.js App Router as the canonical implementation. Do NOT use for read-path data fetching with RSC (use server-components-design), for the broader 'use client' / 'use server' boundary semantics (use client-server-boundary), for designing externally-facing API contracts (use api-design), or for form UX patterns at the component level (use form-ux-architecture).
license	MIT
allowed-tools	Read Grep
metadata	{"metadata":"{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"Server Actions\\\\\\\",\\\\\\\"Server Function declaration\\\\\\\",\\\\\\\"form action attribute\\\\\\\",\\\\\\\"useActionState\\\\\\\",\\\\\\\"useFormStatus\\\\\\\",\\\\\\\"forms that work without JavaScript\\\\\\\",\\\\\\\"revalidatePath\\\\\\\",\\\\\\\"revalidateTag\\\\\\\",\\\\\\\"server mutation Next.js\\\\\\\",\\\\\\\"validate Server Action inputs\\\\\\\",\\\\\\\"bound arguments Server Action\\\\\\\",\\\\\\\"redirect after action\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do I submit a form to the server\\\\\\\",\\\\\\\"do I need an API route for this mutation\\\\\\\",\\\\\\\"how do I call a server function from a button\\\\\\\",\\\\\\\"why is my Server Action exposed as an endpoint\\\\\\\",\\\\\\\"useActionState vs useFormState\\\\\\\",\\\\\\\"how do I revalidate after mutation\\\\\\\",\\\\\\\"can Server Actions run in event handlers\\\\\\\"]\",\"examples\":\"[\\\\\\\"design a 'create comment' form using Server Actions plus useActionState so it works without JavaScript and reports server-side validation errors\\\\\\\",\\\\\\\"decide whether a delete button should call a Server Action or an API route\\\\\\\",\\\\\\\"audit a Server Action for missing authorization (the function looks like a normal call but is publicly invokable)\\\\\\\",\\\\\\\"design the revalidation strategy for a mutation that affects multiple cached routes\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design a Server Component that reads data on render (use server-components-design)\\\\\\\",\\\\\\\"design a public REST API consumed by mobile clients (use api-design)\\\\\\\",\\\\\\\"choose between SSR and SSG (use rendering-models)\\\\\\\",\\\\\\\"design the visual UX of a form's validation states (use form-ux-architecture)\\\\\\\",\\\\\\\"design the visual states and accessibility of a form (use form-ux-architecture)\\\\\\\",\\\\\\\"design a public HTTP contract for mobile, third-party, or server-to-server callers (use api-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"server-components-design\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"form-ux-architecture\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"server-components-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"server-components-design owns the read path — Server Components fetch data on render; server-actions-design owns the write path — Server Actions execute mutations triggered from the client. They share infrastructure (RSC, 'use server') but solve distinct problems.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization and directive mechanics of the boundary itself; server-actions-design owns the discipline of using the 'use server' side of that boundary for mutations.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"api-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Server Actions are to React mutations what stored procedures are to database access — the function looks like an ordinary call in client code, but the work happens on the privileged side of a trust boundary, with the same security implications: the caller controls the arguments, but cannot see the implementation; the implementation must validate every input and authorize every call as if the caller were a hostile script with curl, because functionally they could be.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A Server Action is a JavaScript function marked with 'use server' (either at the module level or as the first line of the function body) that executes on the server but is invokable from the client. The bundler turns calls to it from Client Components into a network round-trip: arguments are serialized, the function runs server-side, the return value is serialized back. The function itself looks like an ordinary import in client code, which is the design's main strength and its main security trap — what looks like a function call is a public PO…","skill_graph_source_repo":"https://github.com/jacob-balslev/skill-graph","skill_graph_protocol":"Skill Metadata Protocol v4","skill_graph_project":"Skill Graph","skill_graph_canonical_skill":"skills/server-actions-design/SKILL.md"}

Server Actions Design

Coverage

The discipline of designing Server Actions: what 'use server' actually does (turns a function into a public POST endpoint with serialized arguments), how Server Actions integrate with HTML forms via the action attribute, how useActionState and useFormStatus give React-aware state and pending UI, why progressive enhancement (form works without JavaScript) is the design's load-bearing feature, why server-side validation and authorization are not optional, how revalidatePath / revalidateTag / redirect participate in the mutation pipeline, how bound arguments propagate state across action calls, and the central security insight: a Server Action that looks like a function call is a publicly-reachable endpoint and must be treated as one.

Philosophy

Before Server Actions, a "mutation from the browser" required two parallel structures: a client-side function that called fetch('/api/foo', { method: 'POST', body: JSON.stringify({...}) }), and a server-side route handler that parsed the body, validated, authorized, executed the mutation, and serialized a response. The two had to agree on a wire format, type contracts had to be duplicated or shared via a runtime validator, and CSRF tokens had to be plumbed through.

Server Actions collapse that into one declaration. A function with 'use server' at its top is invokable from Client Components as if it were imported normally. The bundler rewrites the call site to a network round-trip; the function executes server-side. There is no manual wire format, no client-side fetch boilerplate, no separate API route to keep in sync.

The collapse is syntactic, not semantic. The function is still invoked over the network, by anyone who finds the action's identifier, with arguments they control. The server has none of the type guarantees the call site appears to provide. The discipline of Server Actions is to treat the function as a public endpoint disguised as a function: validate every input, authorize every call, fail loudly on any assumption that the caller is your own UI rather than an attacker with curl.

The second principle of Server Actions is progressive enhancement. A Server Action attached to an HTML form via <form action={serverAction}> works without JavaScript: the browser performs a native POST to the action's endpoint, the server returns a redirect, the page navigates. With JavaScript, React intercepts the submission, runs the action, applies the result without a full page reload, and updates useFormStatus while the action is in flight. The form does not have two code paths — it has one path that gracefully upgrades when JS arrives. Designing actions that rely on JS-only state defeats the architecture; designing actions that work form-first and JS-second uses it well.