Server Actions Design

Server Actions Design

Concept of the skill

Server Actions design is the discipline of using React Server Functions for App Router mutations without forgetting that the function-shaped API is still an HTTP boundary. A form or client transition serializes untrusted values, sends a POST to a generated server endpoint, executes privileged code server-side, then returns action state and optionally refreshed UI — so the practitioner must treat every argument as attacker-controlled and every visible read path as stale until revalidated or refreshed. The model exists because Server Actions reduce duplicated client/server mutation code, preserve form-first progressive enhancement, and integrate with the Next.js cache; but that same convenience can hide authentication, authorization, validation, and cache-invalidation mistakes behind ordinary-looking function calls. It is not Server Component read-path design, a public API contract, the whole client/server serialization model, form visual UX, or general hook discipline: server-components-design owns reads, client-server-boundary owns serialization/directive mechanics, api-design owns stable external HTTP contracts, security-fundamentals checks trust boundaries, form-ux-architecture owns the user-facing form experience, and hooks-patterns owns general Client Component hook rules. The one-line analogy: a Server Action is a privileged back-office operation triggered by a normal form; the form is convenient, but the office still checks identity, authority, and paperwork. The common misconception to correct is that a Server Action is private merely because the client imports it like a function — it is a reachable POST endpoint with framework protections that do not replace authorization or validation.

Coverage

The design discipline for React Server Functions and Next.js Server Actions used as mutations: where to place 'use server', how actions become POST endpoints, how forms invoke actions through action and formAction, how useActionState and useFormStatus expose state and pending UI, how progressive enhancement constrains the design, how to validate and authorize inputs, how to choose cache revalidation primitives, and when to use a route handler or public API instead.

Use the current vocabulary deliberately:

Philosophy of the skill

Before Server Actions, a browser mutation usually required two parallel structures: client code that called fetch('/api/foo', { method: 'POST', body: ... }) and a server route handler that parsed the request, validated it, authorized it, executed the mutation, and serialized a response. The two sides had to agree on a wire format and failure shape.

Server Actions collapse that into one server-side declaration that the UI can bind to a form. This removes boilerplate and drift. It also makes the dangerous part easier to miss: the collapse is syntactic, not semantic. The server still receives serialized input over HTTP from a caller that may not be your UI. Treat the function as a public endpoint disguised as a function.

The second principle is progressive enhancement. A form wired with <form action={serverAction}> can submit before client JavaScript is loaded and can still be enhanced after hydration. Designing the mutation around click handlers, local-only state, or event-only invocation throws away one of the major reasons to use actions.

The 'use server' Contract

Use one of these declaration shapes:

// app/actions/comments.ts
'use server'

export async function createComment(formData: FormData) {
  // runs on the server
}

// app/posts/[id]/page.tsx - Server Component
export default async function PostPage() {
  async function addComment(formData: FormData) {
    'use server'
    // can close over server-side render state
  }

  return <form action={addComment}>...</form>
}

Arguments and return values must be serializable by React. Treat the apparent TypeScript signature as developer ergonomics, not runtime validation. The browser can submit different bytes than the UI would produce.

Form-First Mutation Pattern

The canonical action consumes FormData, validates it on the server, checks the session and permissions, mutates, then updates the read path.

'use server'

import { revalidatePath } from 'next/cache'
import { z } from 'zod'
import { auth } from '@/auth'
import { db } from '@/db'

const CommentInput = z.object({
  postId: z.string().uuid(),
  body: z.string().min(1).max(1000),
})

export async function addComment(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    return { ok: false, error: 'Unauthorized' }
  }

  const parsed = CommentInput.safeParse({
    postId: formData.get('postId'),
    body: formData.get('body'),
  })

  if (!parsed.success) {
    return { ok: false, fieldErrors: parsed.error.flatten().fieldErrors }
  }

  const canComment = await db.post.canComment({
    postId: parsed.data.postId,
    userId: session.user.id,
  })

  if (!canComment) {
    return { ok: false, error: 'Forbidden' }
  }

  await db.comment.create({
    data: {
      postId: parsed.data.postId,
      body: parsed.data.body,
      authorId: session.user.id,
    },
  })

  revalidatePath(`/posts/${parsed.data.postId}`)
  return { ok: true }
}

<form action={addComment}>
  <input type="hidden" name="postId" value={postId} />
  <textarea name="body" required />
  <button type="submit">Post</button>
</form>

Hidden inputs are user-controlled. Use them for convenience, not authority. The action decides whether the authenticated user may mutate the referenced resource.

useActionState and useFormStatus

useActionState wraps an action and gives the client the latest returned state plus a form action to pass into <form action={...}>.

The server function used with useActionState accepts the previous state first and the submitted FormData second. It can delegate to the plain form action if you want one mutation implementation:

'use server'

type CommentState =
  | { ok: true }
  | { ok: false; error?: string; fieldErrors?: Record<string, string[]> }

export async function addCommentWithState(
  _previousState: CommentState,
  formData: FormData,
): Promise<CommentState> {
  return addComment(formData)
}

'use client'

import { useActionState } from 'react'
import { addCommentWithState } from '@/app/actions/comments'

export function CommentForm({ postId }: { postId: string }) {
  const [state, formAction, isPending] = useActionState(addCommentWithState, { ok: true })

  return (
    <form action={formAction}>
      <input type="hidden" name="postId" value={postId} />
      <textarea name="body" />
      {!state.ok && <p>{state.error ?? state.fieldErrors?.body?.[0]}</p>}
      <button disabled={isPending}>{isPending ? 'Posting...' : 'Post'}</button>
    </form>
  )
}

When a function is wrapped by useActionState and used as a form action, React passes the previous state as the first argument and the submitted FormData as the next argument. Design the server function signature for that shape when using the hook.

useFormStatus reads status from a descendant of the nearest parent form.

'use client'

import { useFormStatus } from 'react-dom'

export function SubmitButton() {
  const { pending } = useFormStatus()
  return <button disabled={pending}>{pending ? 'Saving...' : 'Save'}</button>
}

It does not observe a form rendered in the same component that calls the hook. Put the submit button in a child component.

Cache And Navigation After Writes

A mutation that changes data visible to Server Components must update the relevant cached read path or router state.

If the action mutates database state and returns ok: true but never revalidates, the UI can continue showing stale data. Choose the smallest primitive that makes the user's next read correct.

Bound Arguments And Closures

bind can pre-fill action arguments:

const deletePost = deletePostAction.bind(null, post.id)

return (
  <form action={deletePost}>
    <button type="submit">Delete</button>
  </form>
)

Bound values are not a security boundary. Use them to avoid hidden inputs or simplify call sites, but never bind secrets and never skip authorization. Next.js can encrypt closed-over variables for inline actions, but the docs warn not to rely on encryption alone to prevent sensitive exposure. The action must still re-read current server truth and authorize the operation when invoked.

Security Discipline

Use route handlers or api-design instead when the caller is not this App Router UI, when clients need stable URL/method/status semantics, when third parties need documentation, or when a webhook/mobile/server-to-server consumer must call the mutation.

Common Anti-Patterns

Verification

After applying this skill, verify:

• Every action checks authentication before privileged work.
• Every action authorizes the actor against the target resource.
• Every argument from FormData, hidden inputs, bound arguments, URL params, or serialized client calls is parsed server-side.
• Every mutation updates visible read paths with revalidatePath, revalidateTag, updateTag, refresh, or a justified redirect.
• Forms that can be native forms use action or formAction, not a JS-only click handler.
• useActionState actions have the correct previous-state plus payload signature.
• useFormStatus is called in a descendant of the form it observes.
• No secret or authority-bearing value is hidden, bound, or closed over as the only protection.
• Expensive or anonymous actions have rate limiting.
• Return values expose only client-safe data.
• Externally consumed contracts use route handlers or API design instead of generated action endpoints.

Grounding Sources

• React docs - 'use server'. The React directive contract for Server Functions.
• React docs - useActionState. The hook for action state and pending status.
• React docs - useFormStatus. The hook for nearest-parent form status.
• Next.js docs - Mutating Data. Current App Router Server Functions / Server Actions overview.
• Next.js docs - use server. Next.js directive usage and security considerations.
• Next.js docs - Data Security. Public endpoint semantics, authorization, rate limiting, closures, encryption, and audit guidance.
• Next.js docs - serverActions. allowedOrigins and bodySizeLimit configuration.
• Next.js docs - revalidatePath, revalidateTag, updateTag, refresh, and redirect. Cache, router, and navigation primitives after writes.

Do NOT Use When