Server Actions

Server Actions

Server Actions run only on the server, invoked from the client over a POST. They are the App Router's tool for mutations — create, update, delete, form submissions.

Reads don't belong here. Fetch data directly in a Server Component (no HTTP round-trip). Reach for a Server Action only when state changes.

Stack-agnostic: examples use placeholder modules (~/auth, ~/lib/logger, your ORM, your toast library) — swap them. The one thing standardized is the result contract, because a consistent return shape lets every form, hook, and error path compose.

Setup: the result contract

Every action returns a typed discriminated union, not a bare object or a thrown error. Do this once per project before writing actions:

1. Check for an existing definition — grep -rl "ActionResponse" --include="*.ts" lib src app.
2. If none, copy the canonical file assets/action-types.ts into the project: cp <skill-path>/assets/action-types.ts lib/action-types.ts (match the project's layout).
3. If one exists, use it as-is — read it for the exact exported names and import path.

export type ActionResponse<T = unknown> = Promise<
  | { success: true; data: T; message?: string }
  | { success: false; error: string; fieldErrors?: Record<string, string[]> }
>;
// `never` on success because redirect() throws — the function never returns normally.
export type RedirectAction = Promise<never | { success: false; error: string; fieldErrors?: Record<string, string[]> }>;

The success boolean lets TypeScript narrow the result, so the client always knows whether to read data or error/fieldErrors — a thrown error would only surface as an opaque message a form can't display. Reserve throws (or notFound() / unauthorized() / forbidden()) for cases the user can't act on. Full usage in references/types.md.

Workflow

1. Clarify the shape — what's mutated? Returns data or redirects? What needs validation? What auth/ownership rules? Which cache paths become stale?
2. Pick the response type: ActionResponse<T> to return data; RedirectAction to navigate on success; ActionResponse<T> with a (prevState, formData) signature for useActionState.
3. Write the action (anatomy below).
4. Write the Zod schema → references/validation.md.
5. Wire into React → references/hooks.md / references/react-hook-form.md.

Anatomy of an action

Fixed sequence so every action reads the same: directive → auth → validate → mutate → revalidate → return. Keep business logic in the data/service layer; the action only orchestrates.

"use server"; // must be the first statement in the file (or first line inside an inline action)

import { revalidatePath } from "next/cache";
import { auth } from "~/auth";
import { createLogger } from "~/lib/logger";
import type { ActionResponse } from "~/lib/action-types";
import { createThing } from "../db/things"; // data layer → [error, data] tuple
import { thingSchema, type ThingInput } from "../../schemas/thing";

const logger = createLogger({ module: "things-actions" });

export async function createThingAction(input: ThingInput): ActionResponse<Thing> {
  const { userId } = await auth();
  if (!userId) return { success: false, error: "Authentication required" };

  const parsed = thingSchema.safeParse(input); // never trust the client
  if (!parsed.success) {
    return { success: false, error: "Validation failed", fieldErrors: parsed.error.flatten().fieldErrors };
  }

  const [error, thing] = await createThing({ ...parsed.data, ownerId: userId });
  if (error) {
    logger
      .withMetadata({ userId, operation: "createThing", errorCode: error.code })
      .error("Failed to create thing");
    return { success: false, error: "Could not create the item" }; // user-safe message
  }

  revalidatePath("/things"); // only on success
  return { success: true, data: thing, message: "Item created" };
}

A redirect action ends with redirect("/next") instead of returning success (it throws, so nothing after it runs).

Rules that matter on every action

• Validate every input with Zod; return fieldErrors from error.flatten().
• Data layer returns [error, data] (not throws) so the action branches on error kind.
• Never leak internal errors — log the real cause (userId, operation, errorCode); return a short, safe message.
• Revalidate only on success, only affected paths/tags — never revalidatePath("/").
• Toast follows navigation — non-redirect: return message/error, toast client-side; redirect: set a short-lived cookie before redirect(). Never a toast cookie without a redirect.
• Order: authenticate → authorize → validate → mutate.

Detail in references/patterns.md.

React integration

useActionState (simple native form) · React Hook Form + useTransition (rich/typed/dynamic) · useTransition (single button: delete/toggle) · useOptimistic (instant feedback). See references/hooks.md and references/react-hook-form.md.

Reference files

• references/types.md — contract usage, narrowing, guards, useActionState signature.
• references/examples.md — CRUD, redirect, client toast, useActionState, file upload.
• references/patterns.md — errors, logging, cache, security, performance, anti-patterns.
• references/validation.md — Zod schemas, cross-field rules, FormData parsing.
• references/hooks.md — useActionState, useFormStatus, useTransition, useOptimistic.
• references/react-hook-form.md — RHF integration, useFieldArray, wizards, UI binding.

For the logger itself (createLogger, required libraries, full config) see the structured-logging skill's references/setup.md.

Before reporting done

Run the project's type checker (npm run type-check / tsc --noEmit) — a mistyped result contract compiles against the client incorrectly. If a form was touched, exercise it once.