DocsServer
Server components and islands
Pages in routes/ drawn on the server, with client components and islands where something moves.
Files in routes/ are pages drawn on the server. .tsx pages are React server components, and .md pages are Markdown. The browser downloads JavaScript only for the parts that move. To make a page, export a component from a file in routes/:
import { Badge } from "@/components/ui/badge";
import { AddNote, total } from "../components/add-note.tsx";
// Any component can be async and wait for its data.
async function Newest() {
const page = await server.collection("notes").list({ sort: "title" });
return <ul>{page.items.map((n) => <li key={n.id}>{n.title}</li>)}</ul>;
}
export default async function Page() {
// A "use server" function, called directly.
const count = await total();
return (
<main>
<h1>Notes</h1>
<Badge>{count} notes</Badge>
<Newest />
<AddNote start={count} />
</main>
);
}"use client";
import { useState } from "react";
export async function total() {
"use server";
return server.collection("notes").count();
}
export function AddNote({ start }: { start: number }) {
const [count, setCount] = useState(start);
return <button onClick={async () => setCount(await total())}>{count}</button>;
}- Server components run on the server only, and may be
async.serveris Sluurp as whoever asked for the page, so collection rules apply. - Client components are the exports of a file that starts with
"use client": drawn on the server with the page, then brought to life in the browser. Their props keep their types on the way, so aDatestays aDateand aMapaMap, and JSX given to them is sent as HTML. "use server"functions in a client file run on the server: called directly while the page is drawn, and through/api/rpcfrom the browser, their bodies never sent there. See Server functions.- The server-components example has all three.
Features include:
- Routes from file names, with parameters, catch-alls, nested layouts and endpoints
- Markdown pages whose text can calculate with their frontmatter
- Each page’s source at its URL plus
.md, and/llms.txtfor LLMs - Islands, drawn in the browser where their tag is
- The app’s version and changelog from one
CHANGELOG.md
Routes
| File | URL |
|---|---|
routes/index.tsx | / |
routes/docs/sync.md | /docs/sync |
routes/posts/[slug].tsx | /posts/anything (params.slug) |
routes/files/[...rest].tsx | /files/a/b/c |
routes/_layout.js | root layout wrapping every page |
routes/docs/_layout.js | nested layout for pages in docs/ |
routes/contact.ts exporting POST | an endpoint: POST(req, { params, url, input }) |
Pages need no config. A page gets { url, params, query }. By default, pages are public; to limit who sees one, export a rule (export const rule = "@request.auth.id != null"). The title is the first <h1>.
Markdown pages
---
title: Sync
section: Data
order: 3
---
# Sync
A shape is a collection narrowed by a filter…
<sluurp-island src="chart-playground"></sluurp-island>Frontmatter is the page’s data, and the text can calculate with it. {{ … }} is evaluated when the page is served. It takes the frontmatter’s values by name (bench.score for one inside another), numbers, + - * / %, brackets, and round(x, places), ceil, floor, min, max and abs. Whole numbers get thousands separators:
---
score: 2048
---
The score is {{ score }}; a machine twice as fast scores about {{ round(score * 2, -2) }}.That reads “The score is 2,048; a machine twice as fast scores about 4,100.” Change the frontmatter, and every sentence that uses it follows. Code, fenced or inline, is left alone, and so is an expression that can’t be evaluated. So {{ can still be written about.
A folder’s _layout.js receives all sibling Markdown pages with their URLs and frontmatter, which is how this site’s sidebar is made. Islands are just their HTML tag.
Code blocks
Code fences take a few words after the language:
title="app.tsx"shows a file’s name above the code.label="React"shows any label above it, for code shown side by side.src="../app/todo.tsx"shows a file from the app, so the listing is always the code that runs.
To show code side by side, put the fences in <div class="compare">, with an empty line after the opening tag and before the closing one, and style .compare as a grid in your stylesheet.
Pages for LLMs
Each Markdown page’s source is also served at its URL plus .md (/docs/sync.md). The site also gets /llms.txt, an index of all pages for LLMs grouped by section, and /llms-full.txt with every page’s text in one file. routes/_llms.md is prepended (title, summary, usage notes) and its sections sets section order. A static llms.txt file takes precedence.
Faster navigation
To move between pages without a full reload, mark a region as navigable and name the parts that change:
<body sluurp-nav>
<nav>…links…</nav>
<main sluurp-partial="content">…the page…</main>
</body>A click on a link of the same site inside the region fetches the page, takes its sluurp-partial regions out, and merges them into the ones on screen. The rest of the page is never touched, so the header, the navigation and any island outside a partial keep their state, their scroll position and what was typed in them.
- An island inside a partial is replaced when that partial changes; an island outside one survives. Put a media player or a long form outside the partial, and it keeps playing or keeps its text.
- A page is fetched before the click when the pointer rests on its link, a finger touches it, or the keyboard moves to it. To turn that off for one link, add
data-preload="false". It’s skipped when the browser asks to save data. sluurp-view-transitionruns the swap insidedocument.startViewTransition, so the browser animates between the two pages.sluurp-nav="false"turns it off again for part of the region, such as a widget that needs real navigation.- Links that open elsewhere, downloads, links to other sites and clicks with a modifier key work as they always do. If a fetch fails, the browser follows the link itself, so a link never stops working.
Islands
A component in islands/ used by a Markdown page or a layout (<sluurp-island src="chart-playground">) is drawn in the browser where the tag is. A component imported from islands/ by a .tsx page is drawn on the server with it, then taken over in the browser.
Versions and changelogs
An app says its version by keeping a CHANGELOG.md beside its pages, laid out as Keep a Changelog has it. The newest version heading is the app’s version, so there’s no second place to keep in step:
# Changelog
## [Unreleased]
### Added
- Dark mode for reports
## [1.2.0] - 2026-09-29
### Added
- **Exports** to CSV
### Fixed
- Dates in MarchFrom that one file:
- Components.
<Version />shows it as a badge, for a footer or a menu.<Changelog />lists every version with what was added, changed and fixed.limitshows only the newest few, andreleasedleaves out Unreleased. Both come with the registry’schangelog(bunx shadcn add @sluurp/changelog). - Pages. A layout gets
state.app.version. A Markdown page can write{{ app.version }}, or{{ app.changelog }}to put the whole changelog in, headings and all. - Data.
GET /api/app/changeloggives{ version, entries }, each entry with its sections and items.
Sluurp’s own works the same way, from the changelog in its source: sluurp.version, {{ sluurp.changelog }}, GET /api/sluurp/changelog and <Version of="sluurp" />. This site’s version badge and What’s new are made from it.