---
title: "Server actions"
description: "Calling the server from a client component, as an ordinary function."
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.rsc-kit.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Server actions
import CodeFromFile from "@/components/CodeFromFile.astro";
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
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
`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).
## 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:
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.
## 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.
> **A different thing from middleware.ts**
>
> `middleware.ts` in a route directory decides whether a page may render. This
> wraps one action. They are separate because an action is reachable without
> any page — which is why it defends itself.
### 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.'
```
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.
`