server-components · git:20261016.3f36f77 · 2026-10-16 · sha256 98bc2977c9136d9d
server-components git:20261016.3f36f77A
Immutable. This exact content never changes and is served at /api/v1/blob/98bc2977c9136d9d.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_qwaxcsbamejh3f6o/98bc2977c9136d9d9651e514e450e9bf13676b013e8f0c4b06c82c6d349d112d.json
Then /plugin install server-components@markdownregistry-qwaxcsbamejh3f6o in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: server-components
description: Rules for writing Solid 2.0 server components ("use server" functions that return a template) and their slots with @solidjs/web. Use when writing or reviewing a server component, deciding what lives on the server versus the client, or wiring a slot.
---
# Writing Solid server components with slots
A Solid server component is a `"use server"` function that returns a
template; the browser receives its markup and never its code. Anything the
client contributes goes through a **slot** on the component's props: a
client component the client places at a position in the server's markup.
This guide is the set of rules an author — a person or an agent — needs to
write one correctly the first time. The design record is
`documentation/server-components/server-components-principles.md`; this
file is the operative subset.
## Where things go
> **An element lives where the data that creates it lives.**
- Exists because of **server data** (a todo row, a nav link, a search
form the server renders)? It is **server markup**. A mutation on it is a
form `action` — it works without JavaScript, and the router marks a
submission in flight (`aria-busy`) so CSS can show the intent.
- Needs **client behavior or client state** (a handler, an optimistic add,
a modal, a drag ghost, an editor open over a field)? It is a **client
component** placed through a **slot**.
When the client confirms an optimistic entity and the server renders it, the
row _becomes_ server markup; `$key` on the element reconciles the two.
## Slots
```tsx
import type { Slot } from "@solidjs/web/frames";
interface TodosProps {
pending: Slot; // no props
editor: Slot<{ id: string; title: string }>; // props from the server
}
```
A slot is placed as an element: `<props.pending />`,
`<props.editor id={t.id} title={t.title} />`. The client owns the nodes
between the slot's markers; the server's markup around them stays the
server's.
```tsx
export async function todoList() {
"use server";
const todos = await db.list();
return (props: TodosProps) => (
<ul>
{todos.map(t => (
<li $key={t.id}>
{t.title}
<props.editor $key={t.id} id={t.id} title={t.title} />
</li>
))}
<props.pending />
</ul>
);
}
```
The client passes the fill — a component of the slot's props:
```tsx
<Todos editor={p => <Editor id={p.id} title={p.title} />} pending={() => <For each={adds}>{…}</For>} />
```
- **The fill runs once per occurrence, as a component body does.** It runs
untracked, under the occurrence's owner, with live props. State it
creates (a signal, a memo, an `onCleanup`) lives as long as the
occurrence. A top-level read is read once, and `STRICT_READ_UNTRACKED`
names it ("the \`editor\` template-slot fill").
- **Place slots as JSX, not calls.** The compiler wraps each prop in a
getter so the read defers to the slot border; a call form
(`props.status({ … })`) evaluates its args eagerly in the server
component's body.
- **`$key` is optional.** Add it when the fill holds its own state (an edit
draft, a signal created inside) that must follow the entity across
refetches and reorders.
- **An async value crosses with `asyncArg`.**
`<props.status progress={asyncArg(gen.progress)} />` ships the promise or
async iterable; the fill's read settles (suspends until the first value).
## Behavior on server markup
A handler on a server-rendered element cannot come from the server: a
server function never runs in the browser. Pick one:
- **A form.** A mutation is `<form action={…}>`; it works before
JavaScript and needs no client code.
- **A client component that owns the element.** Move the control into a
slot's fill (`<props.toggle id={t.id} done={t.completed} />`, rendering
the checkbox on the client).
- **One delegated listener.** For many identical controls inside server
markup (a copy button on every code block), place one slot occurrence
whose component registers a single document listener in `onSettled` and
finds its target from the event (`closest("button.copy-code")`). Inside a
live hole this is the shape that keeps the hole streaming: a slot placed
inside a live hole latches it (`SSR_LIVE_HOLE_LATCHED`, `data.cause`
`"records"`). `examples/chat`'s Copy button is this shape.
## Shared components
One component can render on both sides. Put `$key={props.id}` on the
element it renders (morph identity) — the slot's own `$key` is a different
key for a different job. Do not read `document`/`window` during render;
that is the ordinary isomorphic rule.
## Compiling
With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
{ components: true } })` is the turnkey setup (the examples under
`examples/todos-server`, `examples/notes`, `examples/chat`).