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/:

routes/notes.tsx
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>
  );
}
components/add-note.tsx
"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. server is 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 a Date stays a Date and a Map a Map, 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/rpc from 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.txt for LLMs
  • Islands, drawn in the browser where their tag is
  • The app’s version and changelog from one CHANGELOG.md

Routes

FileURL
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.jsroot layout wrapping every page
routes/docs/_layout.jsnested layout for pages in docs/
routes/contact.ts exporting POSTan 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

routes/docs/sync.md
---
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:

routes/_layout.js
<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-transition runs the swap inside document.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.md
# Changelog

## [Unreleased]
### Added
- Dark mode for reports

## [1.2.0] - 2026-09-29
### Added
- **Exports** to CSV
### Fixed
- Dates in March

From 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. limit shows only the newest few, and released leaves out Unreleased. Both come with the registry’s changelog (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/changelog gives { 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.

View as Markdown