Next.js Server Actions · Metis Knowledge Center

TL;DR

Server Actions are great for route-local mutations, especially forms, when I want server-owned validation and fewer custom client fetch wrappers.
They reduce plumbing, but they are still server endpoints in practice, so I treat auth, authorization, validation, and idempotency seriously.
The winning pattern is usually: server action for the write, explicit cache update or revalidation, and a stable UI state model for pending and expected errors.
If multiple clients need the same contract, or the mutation boundary is broader than one route, I still prefer an explicit API.

Context

Server Actions can simplify a codebase fast, but they are easy to misuse.

The good use case is common: a form or button in one route needs a server mutation, and I do not want to create a separate route handler or REST endpoint just to forward the request.

The bad use case is also common: teams start hiding broad backend logic inside action files, and the mutation boundary becomes harder to reason about because it looks like a local function call even though it is still a networked server operation.

The Approach

1. Use Server Actions where the write belongs to the UI surface

My default fit criteria:

one route owns the interaction
the browser should not see the underlying credentials or write path details
the server should remain authoritative for validation
progressive enhancement is useful
no other client needs the same mutation contract

2. Design the mutation as a real server contract

I still design the action as if it were a public write boundary:

validate input
authenticate and authorize
persist or call downstream services
update or invalidate the relevant cache
return expected errors as data
throw unexpected failures to the nearest error boundary

"use server"

import { updateTag } from "next/cache"

type FormState = {
  fieldErrors: Record<string, string>
  message: string
}

export async function createNote(previousState: FormState, formData: FormData): Promise<FormState> {
  const title = String(formData.get("title") || "").trim()

  if (!title) {
    return {
      fieldErrors: { title: "Title is required" },
      message: "",
    }
  }

  const session = await requireSession()
  await db.note.create({
    data: {
      title,
      ownerId: session.userId,
    },
  })

  updateTag("notes")

  return {
    fieldErrors: {},
    message: "Saved",
  }
}

This keeps expected validation failure out of the exception channel, which makes the UI simpler.

3. Pair the action with explicit pending and error UI

Current React and Next.js form flows make this much nicer with useActionState and useFormStatus.

"use client"

import { useActionState } from "react"
import { useFormStatus } from "react-dom"
import { createNote } from "./actions"

const initialState = {
  fieldErrors: {},
  message: "",
}

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

export function NoteForm() {
  const [state, formAction] = useActionState(createNote, initialState)

  return (
    <form action={formAction}>
      <input name="title" aria-invalid={Boolean(state.fieldErrors.title)} />
      {state.fieldErrors.title && <p>{state.fieldErrors.title}</p>}
      <SubmitButton />
      {state.message && <p>{state.message}</p>}
    </form>
  )
}

This gives me:

progressive enhancement
server-owned mutation logic
pending state without custom fetch plumbing
expected-error handling without inventing a second client protocol

4. Be explicit about cache consequences

The write path is not done when the database write finishes.

I still need to decide:

should the current route update immediately?
do I want read-your-own-writes behavior?
should related lists refresh in the background?

That is where cache APIs matter:

updateTag() for immediate expiration in Server Actions when read-your-own-writes matters
revalidateTag() for stale-while-revalidate behavior
revalidatePath() when the route boundary is the right invalidation unit

5. Remember the security model

The current Next.js docs explicitly call out that Server Functions are reachable by direct POST requests and should be treated like public-facing endpoints. That matters.

My rules:

never trust client-provided identity
always verify auth and authorization on the server
validate and narrow all inputs
design idempotency when retries can happen
keep side effects observable in logs and traces

Because the syntax looks local, teams sometimes forget the threat model. I do not.

6. Know when to prefer an explicit API

I still choose Route Handlers or another API surface when:

mobile or partner clients need the same contract
the mutation is not route-local
I need explicit HTTP versioning or broader protocol control
the domain logic belongs to a shared platform service, not the frontend repo

Trade-offs

Server Actions reduce client boilerplate, but they can make server boundaries feel deceptively implicit if the team is not disciplined.
They are excellent for route-local forms, but they are the wrong abstraction for shared cross-client APIs.
The developer experience is strong, but operational visibility can lag if I do not add logging, metrics, and error taxonomy deliberately.
Cache invalidation is still the hard part; Server Actions only move where I solve it.