Server Actions

A function the browser can call

The tea shop's Mint tea page lists its reviews and has a box to write a new one. Saving a review means changing data on the server. In a client-rendered React app you would write an API address for it and fetch it from the browser. In Next.js you write a function, mark it "use server", and hand it to the form. The function stays on the server, and the page calls it anyway. Your first Next.js app saved a note this way; here is the same idea for reviews, recorded from real Next.js 16.4.3 and real Chrome.

1"use server";2 3import { revalidatePath } from "next/cache";4import { saveReview } from "./reviews";5 6export async function addReview(formData: FormData) {7  const text = String(formData.get("text") ?? "").trim();8  if (text) await saveReview(text);9  revalidatePath("/");10}

Line 1 of app/actions.ts is "use server", a directive: a line of text that tells the build how to treat the code after it. Here it says that every function this file exports may be called from the browser. React calls such a function a Server Function, and one that a form or a transition calls to change data is a Server Action. Lines 6 to 10 are addReview. It gets the form's fields as formData, a FormData object. Line 7 reads the field named text, line 8 saves it, and line 9 tells Next.js that the stored HTML of / is out of date.

In app/page.tsx, line 14 hands the function to the form: <form action={addReview}>. The Steps tab is open on step 3, the click on Post review, after Chrome typed Smooth and calm. into the box. It made one request: a fetch, POST /, to the page's own address, with a next-action header. The answer is 200 with text/x-component. The review appeared in the list, the box is empty again, and the page never reloaded.

Writing a Server Action

"use server" goes in one of two places. At the very top of a file, before the imports, it makes every exported function an action, as in app/actions.ts. Or at the top of one async function's body, inside a Server Component: an inline action, which only that component can hand out. Try both, and two places where it doesn't work. Each button is one version of the review page, built with real Next.js. Before you click, guess which ones build.

1"use server";2 3import { revalidatePath } from "next/cache";4import { saveReview } from "./reviews";5 6export async function addReview(formData: FormData) {7  const text = String(formData.get("text") ?? "").trim();8  if (text) await saveReview(text);9  revalidatePath("/");10}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

Two build and two don't:

• At the top of a file is the usual place. Server Components and Client Components can both import the actions, and one file can hold all of a feature's actions.
• Inside a Server Component, line 8 of app/page.tsx starts the body of addReview. An inline action can use the component's variables, like a tea's id; Next.js's docs say it encrypts the ones the action uses before they travel to the browser and back.
• Inside a Client Component, the build stops: It is not allowed to define inline "use server" annotated Server Actions in Client Components. The error names the two fixes: import the action from a file that starts with "use server", or pass it down as a prop from a Server Component, as Composing Server and Client Components did with addAction.
• On a function that isn't async, the build stops too: Server Actions must be async functions. A call from the browser is a network request, which always takes time, so the function has to return a promise.

Each row is one place for the directive, what it marks, and who can call what it marks:

Calling one from a form

<form action={addReview}> is React's way to connect a form to a function (Form actions). When the visitor submits, React calls the function with the form's fields, in a transition. With a Server Action, the form also works before the page's JavaScript has loaded, or on a phone where it never does. Building a page so that it works as plain HTML first, and better once its JavaScript runs, is called progressive enhancement.

The recording shows both ways. Open the Network tab of the example above and pick /: the HTML's form says method="POST", with a hidden field named $ACTION_ID_ and a long code, which names the action. Then pick POST /, press Post review, before JavaScript: the recorder sent the form with Lovely with honey. the way a browser does with no JavaScript at all. Your first Next.js app's action ended with redirect() and got a 303. This one doesn't redirect, so the answer is the page itself: 200, a whole HTML page that already lists Lovely with honey., which the browser loads. The next request, / after posting, says x-nextjs-cache: MISS: line 9's revalidatePath made Next.js render the page again.

Each row compares the same press of Post review, before and after the JavaScript has loaded:

One more thing changed with JavaScript: the box is empty after step 3. After a form's action finishes without an error, React resets the form's uncontrolled fields, the ones whose value you don't keep in state yourself. A field you control with value and onChange keeps what's in your state. To show errors next to the box and keep what the visitor typed, the Forms lesson in this stage uses useActionState.

Calling one from a click

Not every change has a form. An Add to cart button sends only the tea's id. A Client Component can import an action from a "use server" file and call it from an event handler, like any async function:

1"use client";2 3import { useTransition } from "react";4import { addToCart } from "./actions";5 6export default function AddButton({ id, name }: { id: string; name: string }) {7  const [isPending, startTransition] = useTransition();8 9  function add() {10    startTransition(async () => {11      await addToCart(id);12    });13  }14 15  return <button onClick={add}>{isPending ? `Adding ${name}…` : `Add ${name}`}</button>;16}

In app/add-button.tsx, line 4 imports addToCart from app/actions.ts. Line 7 calls useTransition, which gives back isPending and startTransition. Lines 9 to 13 are the click handler: it calls addToCart(id) inside startTransition. react.dev asks for this outside forms: a form puts the call in a transition for you, and a button doesn't. While the transition runs, isPending is true, and line 15 shows Adding Mint tea….

In app/actions.ts, addToCart prints a line, waits for addTea from app/cart.ts, prints another, and calls revalidatePath("/"). The stand-in database in app/cart.ts takes three seconds, so the wait is easy to see. The Steps tab is open on step 2, the click: the button says Adding Mint tea…, and Chrome sent one POST / with a next-action header that had no answer yet when the step ended. Step 3 waited for the cart: In your cart: Mint tea, and no new request. The answer to step 2's POST carried the updated page, because the action called revalidatePath. Next.js's docs call this a single round trip: the action's result and the new page in one response. The Terminal tab shows what next start printed: addToCart(mint) started, then addToCart(mint) finished.

The argument, "mint", travels in the request's body. Arguments and return values must be serializable, and only the id crosses here; addTea looks the tea up on the server. The docs also show an action called from an Effect, like counting a view once a page opens, inside startTransition as well.

Actions run one at a time

What if the visitor clicks Add Mint tea and then, before it's done, Add Green tea? The recorder did exactly that in real Chrome. Before you open the Steps tab, guess: does Chrome send the second POST right away?

1"use server";2 3import { revalidatePath } from "next/cache";4import { addTea } from "./cart";5 6export async function addToCart(id: string) {7  console.log(`addToCart(${id}) started`);8  await addTea(id);9  console.log(`addToCart(${id}) finished`);10  revalidatePath("/");11}

Step 2 clicked Add Mint tea: one POST /, with no answer yet. Step 3, open now, clicked Add Green tea while the first was still running. Both buttons say Adding…, yet step 3 lists no request at all. Step 4 waited for both teas, and lists one POST /: the green one, sent after the mint one had answered. The Terminal tab agrees, line by line: addToCart(mint) started, addToCart(mint) finished, and only then addToCart(green) started and addToCart(green) finished.

That's by design. Next.js's docs say it dispatches Server Actions one at a time for each client: the second waits for the first to finish, so the page the router shows always matches the action that produced it. Three things follow:

• The server doesn't queue them. The line is in the browser's copy of the router. Each action is its own request, and the server runs whatever arrives, so two browser tabs, or two visitors, can run actions at the same time.
• Promise.all doesn't make them parallel. Calling two actions at once from the same page still sends them one after the other. For work that must happen together, do it inside one action.
• Actions are for changes, not for reading. react.dev says Server Functions are designed for changes, not for loading data, and that frameworks run them one at a time and don't cache what they return. Read in Server Components, or from a Route Handler in the browser, as Fetching in the browser does.

What an action's request looks like

Every recording so far shows the same kind of request. Here are its parts, as far as the Steps and Network tabs show them. Each row is one part, with the JavaScript loaded and without it:

• It's a POST to the page you're on. There's no address of its own. The docs say only POST can call an action, and the recordings never show another method.
• The next-action header names the action with an id the build gave it. Both clicks in the last example sent the same id, because they called the same function; the tea's id was in the body. In the review recording, the form's hidden field and the header carry the same id.
• The answer is an RSC payload, text/x-component: the action's return value and, when the action changed what the page shows, the page rendered again. The request also carries a next-router-state-tree header, the router's description of what's on the screen, which the server uses when it renders the page again.

How the body and the payload are written, and how the build makes the ids, belong to the Under the hood stage. One more answer is possible: when an action calls redirect(), the payload holds the new page and the router moves there, with status 200, as Redirects in Next.js recorded.

Every action is a public endpoint

An endpoint is an address on a server that anyone on the internet can send a request to. A Server Action is one, even though you never wrote an address. The recorder proves it: its POST / before JavaScript wasn't sent by a browser at all, only by a small program that copied the form's fields. Any program can do the same with any action whose id it has, and send whatever arguments it likes.

So the action itself is where the checks go. Next.js's docs list them:

• Check who's asking, and whether they may. Showing the form only to signed-in staff protects nothing, because the request can come without the form.
• Check every argument. formData and every other argument come from the visitor. Line 10 of app/cart.ts refuses an id that isn't a tea, because the button isn't the only way to send one.
• Return only what the page needs. Whatever an action returns travels to the browser.

Next.js adds a few protections of its own, which the docs describe: it compares the request's Origin header with the site's address and refuses actions sent from other sites' pages, it limits a request's body to 1 MB unless you change it, it makes action ids hard to guess and leaves out the ones no page uses, and it encrypts the variables an inline action captures. None of them knows who your visitor is. Securing Server Actions calls an action from outside the page and goes through each of them.

Planning the tea shop's actions

Each change in the shop needs a way to call its action. Forms suit anything with fields, and they work before the JavaScript loads. Buttons without fields call the action from a click, in a transition. And some things aren't changes at all. Sort these jobs:

The third group is the one people miss. An action can return data, but actions run one at a time and aren't meant for reading, so data that only needs to be shown comes from a Server Component, or from a Route Handler when the browser has to ask.

Common mix-ups

• ""use server" makes a Server Component." No. Components are Server Components without any directive. "use server" marks functions the browser may call.
• "A Server Action has its own API address." No. It's a POST to the page it's called from, with a next-action header.
• "Only my form can call my action." No. Anyone can send the same POST. Check who's asking and what they sent inside the action.
• "A form with an action needs JavaScript." No. The recorder posted the review form with none, and the review was saved.
• "Two quick clicks run two actions at once." No. Next.js sends the second after the first has answered, even with Promise.all.
• "Server Actions are a good way to load data." No. They're for changes. Read data in Server Components or from Route Handlers.
• "A Client Component can write its own action." No. It imports one from a "use server" file, or gets one as a prop.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

"use server";

import { revalidatePath } from "next/cache";
import { saveReview } from "./reviews";

export async function addReview(formData: FormData) {
  const text = String(formData.get("text") ?? "").trim();
  if (text) await saveReview(text);
  revalidatePath("/");
}

"use client";

import { saveReview } from "./reviews";

export default function ReviewForm() {
  async function addReview(formData: FormData) {
    "use server";
    await saveReview(String(formData.get("text") ?? ""));
  }

  return (
    <form action={addReview}>
      <input name="text" aria-label="Review" />
      <button>Post review</button>
    </form>
  );
}

"use client";

import { addReview } from "./actions";

export default function ReviewForm() {
  return (
    <form action={addReview}>
      <input name="text" aria-label="Review" />
      <button>Post review</button>
    </form>
  );
}

"use client";

import { addToCart } from "./actions";

export default function AddButton({ id, name }: { id: string; name: string }) {
  return <button onClick={() => addToCart(id)}>Add {name}</button>;
}

"use client";

import { useTransition } from "react";
import { addToCart } from "./actions";

export default function AddButton({ id, name }: { id: string; name: string }) {
  const [isPending, startTransition] = useTransition();

  function add() {
    startTransition(async () => {
      await addToCart(id);
    });
  }

  return <button onClick={add}>{isPending ? `Adding ${name}…` : `Add ${name}`}</button>;
}

"use client";

import { useTransition } from "react";
import { addToCart } from "./actions";

export default function AddBoth() {
  const [isPending, startTransition] = useTransition();

  function addBoth() {
    startTransition(async () => {
      await Promise.all([addToCart("mint"), addToCart("green")]);
    });
  }

  return <button onClick={addBoth}>{isPending ? "Adding both…" : "Add both"}</button>;
}

"use server";

import { revalidatePath } from "next/cache";
import { saveReview } from "./reviews";

export function addReview(formData: FormData) {
  const text = String(formData.get("text") ?? "").trim();
  if (text) saveReview(text);
  revalidatePath("/");
}

"use server";

import { revalidatePath } from "next/cache";
import { saveReview } from "./reviews";

export async function addReview(formData: FormData) {
  const text = String(formData.get("text") ?? "").trim();
  if (text) await saveReview(text);
  revalidatePath("/");
}

Check your understanding

For each question, ask where the function runs, and what travels between the browser and the server.

Key takeaways

• "use server" at the top of a file makes every export a Server Action; at the top of an async function in a Server Component, it makes that one. Client Components import actions or get them as props.
• A form calls an action with its fields, and works before the JavaScript loads: the browser posts the form and gets a page, or follows a 303 when the action redirects.
• With JavaScript, a call is a fetch: POST to the page, with a next-action header, answered with an RSC payload that can hold the updated page.
• Outside forms, call actions in startTransition, and show isPending while they run.
• Next.js sends a page's actions one at a time; the server doesn't queue them. Use actions for changes, not for reading.
• Every action is a public endpoint. Check who's asking and every argument inside it.

Coming next: Forms. It validates what the visitor typed on the server, shows errors next to the fields, and keeps the text with useActionState.