# Server actions > Calling the server from a client component, as an ordinary function. A server action is an async function a client component can call directly. Mark the module `"use server"` and its exports become callable from the browser; the body stays on the server. ## Writing one ```ts title="src/actions.ts" 'use server' import { revalidate } from '@rsc-kit/core/revalidate' import { addOrder } from './orders' let total = 0 // Called straight from a client component as an ordinary async function. The // body never reaches the browser; the call becomes a POST to /_rsc/action. export async function addToTotal(amount: number): Promise { total += amount return total } // Marks the orders list stale. The re-rendered list travels back with this // action's own answer, so the client never makes a second request for it. export async function placeOrder(item: string): Promise<{ ok: true }> { await addOrder(item) revalidate('orders') return { ok: true } } ``` Nothing is registered and nothing is generated. The build turns each export into a reference, and the import in a client component resolves to a stub that performs the call. ## Calling one ```tsx title="src/components/AddOrder.tsx" 'use client' import { useState } from 'react' import { placeOrder } from '../actions' export function AddOrder() { const [item, setItem] = useState('') const [note, setNote] = useState('') return (
setItem(e.target.value)} placeholder="Item" id="item" /> {/* Deliberately untouched by the action: proof the page was not replaced. */} setNote(e.target.value)} placeholder="A note" id="note" />
) } ``` `import { placeOrder }` does not pull `actions.ts` into the browser bundle. Anything that module imports — a database client, a secret — stays on the server with it. ## What happens on the wire 1. The client component calls the function. 2. React serialises the arguments in the Flight format. 3. The browser sends one `POST /_rsc/action` carrying the action's id and the encoded arguments. 4. The host decodes them and runs the real function. 5. The return value is serialised as Flight and streamed back. Files travel this way too, without any encoding of your own — see [File uploads](/guides/file-uploads). The id is a hash of the module and the export in a build — `9396f92f746f#createOrder` — and nothing about the file is in it. In development it is the module's path as Vite serves it (`/@fs/Users/…/actions.ts#createOrder`), which is what a `$ACTION_ID_…` hidden input in a form shows there; a build never carries it. ## Returning UI Step 5 is the same serialiser a page goes through, so an action can answer with elements instead of data — server components, client components, Suspense boundaries — and the caller receives real React elements to render: ```tsx title="src/actions.tsx" 'use server'; import { Suspense } from 'react'; import { Counter } from './Counter'; export async function renderCard(name: string) { return (

{name}

loading…

}>
); } ``` ```tsx title="src/CardButton.tsx" 'use client'; const [ui, setUi] = useState(null); {ui} ``` The answer streams. The promise resolves as soon as the root row arrives, so the card mounts with its fallback showing, and `` fills the hole when it is done — the action did not wait for it. The browser never receives ``'s code: it ran on the server, and only its output crossed. ### Streaming tokens That is the primitive behind "generative UI". An async component that renders one chunk and suspends on the next is a streamed answer, with nothing to install: ```tsx title="src/actions.tsx" 'use server'; export async function ask(prompt: string) { const tokens = model.stream(prompt); // an AsyncIterator return ( thinking…

}> ); } async function Tokens({ from }: { from: AsyncIterator }) { const { value, done } = await from.next(); if (done) return null; return ( <> {value} ); } ``` Each token is a row in the stream and each `` a hole the next one fills. That is what `createStreamableUI` from Vercel's AI SDK does under the hood, in Next as here — the same React serialiser. Reach for it when the server knows what to render and the client should not: a card, a chart, a widget. A chat wants data streamed to the client instead (`streamText` and `useChat` in the AI SDK), because a half-streamed element tree cannot be cancelled, resumed, retried or persisted, and this one is a tree as deep as the token count. ## Refreshing what the action changed An action that changes data usually makes something on screen wrong. Mark it stale with `revalidate`, and the re-rendered content travels back **with the action's own answer**: `placeOrder` in the module above does exactly that: it writes the order, then calls `revalidate('orders')`. The tag names a section — a region of the page registered under a name the server can address on its own: ```tsx title="src/app/orders/orders.section.tsx" import { section } from '@rsc-kit/core/section' import { listOrders } from '../../orders' // A named region. section() registers it under a name the client can refresh // and an action can mark, so this list re-renders without the page around it // being touched. async function Orders() { const orders = await listOrders() return (
    {orders.map((order) => (
  • {order.item}
    • ))}
) } export default section('orders', Orders) ``` One request, not two: the caller sees only what its action returned, and the page updates around it. Nothing else is re-rendered — which is what the second input in `AddOrder` is there to prove. Type into it, place an order, and what you typed is still there. `section()` is deliberately not a client module. The boundary it wraps things in is one, but the thing it wraps is a server component that fetches its own data, and a client reference cannot be async. Three things follow from an action that revalidated, and none of them needs code: - **What is re-rendered replaces what is on screen in place.** `revalidate('page')` and `revalidate('all')` render the same tree a navigation to the page would, so a form's state, a modal opened from `onSuccess`, a toast in the layout all survive. A one-time secret shown after the action is still there. - **The re-render sees the write.** A `cache()`d read the middleware or the action made before the write is forgotten before the page renders again, so a renamed row is renamed in the sidebar too, not only in the table. - **What was fetched before the write is dropped.** Payloads prefetched for other links and the pages held behind this one for the back button are from before the mutation. A visit to the list after creating a row fetches the list, with the row in it, rather than revealing the one prefetched a moment earlier. `refresh()` does the same. - **What comes back is for the page it was invoked on.** A tap that left the page while the action was in flight — Add to cart, then the brand link at once — changed what is showing, and the trees the host rendered for the page before are not put under the url after. The page on screen was fetched before the write, so it is asked for again whole, as `refresh('all')` would; a modal opened over the page in the meantime does not count as leaving it. ## Building one with a schema and middleware A bare `"use server"` function takes whatever it is given and defends itself by hand. `createActionClient` gives you a shape where the checking, the context and the types come from one declaration: ```ts title="src/lib/action.ts" import { createActionClient } from '@rsc-kit/core/action'; export const action = createActionClient({ // Everything reaching here is a bug or an outage, and its message may name a // query, a path, a host. Say something fixed unless you raised it yourself. onError: (error) => (error instanceof AppError ? error.message : 'Something went wrong.'), }); ``` ```ts title="src/actions.ts" 'use server' import { z } from 'zod'; import { action } from './lib/action'; export const createPost = action .use(async ({ next }) => next({ ctx: { user: await currentUser() } })) .use(async ({ ctx, next }) => { if (!ctx.user) throw new AppError('Sign in first'); return next({ ctx: { audit: `user:${ctx.user.id}` } }); }) .input(z.object({ title: z.string().min(3), body: z.string().min(10) })) .handler(async ({ input, ctx }) => { return savePost({ ...input, authorId: ctx.user.id }); }); ``` `input` is typed from the schema and `ctx` from every middleware that ran, so the handler is checked against both without either being written twice. Add a `.use()` and the handler's `ctx` grows; change the schema and the handler stops compiling. Middleware runs outermost first and wraps what follows, so a step can time or clean up around the rest, not only check before it. Throw to refuse. Return what `next()` gave you — it carries the value from everything inside. A step that neither calls `next()` nor throws is reported as a mistake, because a forgotten `next()` would otherwise look exactly like a check that passed. ### Failures come back, they are not thrown ```ts const result = await createPost({ title: 'x', body: 'y' }); result.data // what the handler returned result.validationErrors // { title: ['Too short'] } result.serverError // 'Something went wrong.' result.redirected // '/dashboard' - it redirect()ed ``` Always an object. An action that `redirect()`s resolves with `redirected` set once the navigation is under way — the page is on its way elsewhere — and every other field reads `undefined`, never a `TypeError` inside a transition. The argument is typed by the schema: `createPost({ title: 1 })` fails the typecheck, and so does `createPost()` when the schema takes input. `FormData` is accepted beside it, which is how a form calls the same action. Returned rather than thrown, and that is not a style choice: React serialises a rejected server action opaquely — production strips the message and leaves a digest — so a thrown validation error reaches the browser as "an error occurred" with the fields it named gone. A returned object crosses intact. `
` reads that shape directly, so there is nothing to wire: ```tsx ``` The schema then runs twice, in the two places it has to: in the browser so a mistake costs no round trip, and in the action because the action is a public endpoint reachable without the form. ### From a button Without a form, `useAction` is the transition around the call and the last result, with callbacks that say which way it went: ```tsx title="src/app/posts/archive-button.tsx" 'use client' import { useOptimistic } from 'react' import { useAction } from '@rsc-kit/core/useAction' import { archivePost } from './actions' export function Posts({ posts }) { const [shown, hide] = useOptimistic(posts, (list, id: number) => list.filter((p) => p.id !== id)) const { execute, isPending } = useAction(archivePost, { optimistic: ({ id }) => hide(id), onError: (message) => toast.error(message), }) return shown.map((post) => ( )) } ``` - `execute` takes what the action's schema takes, and `onSuccess` is handed what its handler returned. `executeAsync` resolves with the result. - `onError` gets a `serverError`, or the first validation message, so a button with no field beside it still has something to show. `onSettled` runs after either. - `optimistic` runs inside the action's transition, before the call — where React's `useOptimistic` setter has to be. A failed action takes the change back on its own, because the optimistic state ends with the transition. - Neither call throws. Anything thrown on the way, the network included, becomes a `serverError`, so the transition always settles. - An action that redirected runs no callback and sets no state: the page is leaving. - `status` is `"idle"`, `"executing"`, `"hasSucceeded"` or `"hasErrored"`, `result` is the last answer, and `reset()` forgets it. `execute` keeps one identity across renders, and reads the newest callbacks when it runs. ### Failing on something a schema cannot know ```ts .handler(async ({ input, fieldErrors }) => { if (await slugTaken(input.slug)) return fieldErrors({ slug: 'Already taken' }); return save(input); }) ``` It arrives as `validationErrors`, on the field you named, exactly like a schema failure — so the form renders it in the same place with no extra handling. `fieldErrors` comes in with the handler's arguments rather than being imported, and that is what makes it typed: the field names are the schema's, so `fieldErrors({ slgu: … })` does not compile. There is nothing to pass — the handler already knows its input. **Write `return fieldErrors(…)`.** It throws either way, so nothing after it runs — but TypeScript cannot see that from a destructured argument. Without the `return`, a `user` you checked is still `possibly undefined` on the next line. With it, the type narrows and the code reads as what it is: this branch is over. A forgotten `return` is not a runtime bug; it is a type error that tells you to add one. A string is one message; an array is several. The empty key is the whole submission, for a refusal that is about no field in particular: ```ts return fieldErrors({ '': 'Sign-ups are closed for the weekend' }); ``` :::note[Porting from next-safe-action] `return returnValidationErrors(schema, { email: { _errors: ['Account not found'] } })` becomes `return fieldErrors({ email: 'Account not found' })`. No schema argument, because the typing comes from the handler, and no `_errors` nesting. ::: ## Setting a cookie Signing someone in is a mutation whose entire result is a cookie, so an action can write one: ```ts 'use server'; import { cookies } from '@rsc-kit/core/request'; export async function login(formData: FormData) { const session = await authenticate(formData); (await cookies()).set('session', session.token, { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 60 * 60 * 24 * 7, }); } ``` It lands on the action's own response, so the next navigation already carries it. `delete` expires one, which is what signing out is. That `get`/`set`/`delete` trio is the whole surface an auth library needs, so one can be wired in without this package having an opinion about which. See [Writing to the response](/guides/authorization#writing-to-the-response) for where else it works, and where it does not. ## Work the visitor should not wait for An audit row, a welcome email, a cache warm: the action's answer should not wait for it, and it must still finish. `after()` queues work to run once the answer is on its way: ```ts 'use server'; import { after } from '@rsc-kit/core/request'; export async function signup(formData: FormData) { const user = await createUser(formData); after(() => sendWelcomeEmail(user)); after(() => audit('signup', user.id)); redirect('/welcome'); } ``` Why not a detached promise: on a long-lived process it happens to run to completion; on a Worker the isolate is torn down when the response ends unless the work was handed to the platform's `waitUntil`, so a promise nobody awaited dies silently — some of the time, which is the worst way. `after()` is the same call on every host: handed to `waitUntil` where one exists, kept by the process elsewhere. A rejection is reported to the log and never reaches the response, which has already gone. It works from a component, a `middleware.ts`, an api route and an action alike; outside a request — a build — the work simply runs. ## Two at once Nothing queues them. Each call is an ordinary `fetch`, so two submits fired together really do overlap — they are not serialised behind one another. That is a difference from Next, which runs one server action at a time per client — and it is worth being deliberate about, because Next's queue was doing something for you that you may not have noticed. A double-clicked "add to cart" sends two calls either way. Next runs them one after the other; here they run together. So if a handler reads a value, changes it and writes it back, two of them can lose an update. That is ordinary database concurrency, which a per-client queue was quietly absorbing for you. Fix it where you would fix it anywhere else: - do the read and the write in one transaction - use an atomic update instead of read-modify-write - accept an idempotency key from the form None of that is new advice. It just stops being optional. The engine itself is safe under concurrency, and that part is tested rather than assumed: two actions running at the same moment each get their own request scope, so their cookies, headers and revalidation marks never reach each other's response. An action's answer can carry a re-rendered region with it, and applying two of those is last-response-wins. Two actions that both `revalidate('orders')` will leave whichever response *arrived* last on screen, which is usually the one that committed last — but not necessarily, and nothing detects the difference. Fire as many as you like when they touch different things. When several touch the same region, either let the last answer win or serialise them yourself. `` gives you `pending` for that. It does not guard itself, so a double-click sends two requests unless you disable the button. ## Errors An action that fails does not answer with a Flight stream, so the client turns the response into an error before the decoder ever sees it: | Response | What the client does | What you do | | --- | --- | --- | | `X-RSC-Redirect` header | Starts the navigation and **resolves** with `{ redirected }` | Nothing — the page is on its way to the location, and there is nothing to catch. | | `422` | Throws `ServerValidationError`, carrying `errors` | Show the messages. `` does it for you. | | Any other failure | Throws `Error`, naming the status | Whatever the app needs. | ```tsx "use client"; import { ServerValidationError } from '@rsc-kit/core/errors'; import { createPost } from '../actions'; try { await createPost(title, body); } catch (error) { if (error instanceof ServerValidationError) { // error.errors — { title: ['Too short'], body: ['Required'] } } } ``` A redirect is treated as an instruction rather than something to display: an expired session answers that way, and the right response is the login page, not a message about one. See [Validation](/guides/validation) for the form-shaped version of the same flow, which needs no `try`/`catch` at all.