# Sluurp

> Sluurp is a single executable that serves a backend and its app: SQLite collections with rules enforced in SQL, REST, realtime and sync APIs, auth, an admin UI at `/_/`, server-rendered pages with islands, and a UI kit. No build step, no `npm install`.

Each page below links to its Markdown source. `/llms-full.txt` holds every page's text in one file.

## How to work with Sluurp

- **An app is a folder**, served with `sluurp serve --public ./my-app`. File location decides behaviour: `routes/` for server-rendered pages, `islands/` for components hydrated in the browser, and `functions/`, `hooks/`, `jobs/`, `agents/` and `views/` for server code. The data model lives in `schema.json`. No config file.
- **No build.** TypeScript and JSX are compiled on the fly. Imports use bare names from the import map Sluurp injects into every page: `sluurp` (client), `sluurp/reactive` (signals), `sluurp/ui` (JSX runtime), `sluurp/kit` (shadcn-style components), `sluurp/sync`, `sluurp/pages`, and more. Add npm packages with `sluurp add <package>`, which vendors their source into `vendor/`. `tsconfig.json` is generated.
- **Styling is Tailwind** in markup; the stylesheet is generated from used classes. Theme colours are CSS variables, as in shadcn.
- **Data** goes through the `sluurp` client: `sluurp.collection("todos").list({ filter, sort })`, `.create()`, `.update()`, `.delete()`. Use a Sync shape (`sluurp/sync`) for lists that stay current. Every call is checked against the collection's rules, compiled into SQL. Server code uses the same API via `server`, acting as the caller.
- **Server code** runs in a QuickJS sandbox: no file system, no `process`, network only via `fetch` to public addresses, with a memory limit and timeout per call.

## How to write a website with Sluurp

- **Markdown pages** are `.md` files under `routes/`; `routes/docs/sync.md` is `/docs/sync`. Frontmatter sets `title`, `description`, and optionally `section` and `order` for a sidebar. Code fences accept `title="file.ts"` and are highlighted server-side.
- **TSX pages** are `routes/*.tsx`; the default export is rendered on the server. Load data with `export async function load()` and embed islands.
- **Layouts** are `_layout.js` files: `render(state, html)` wraps every page in that folder and below. `state.pages` lists sibling Markdown pages with frontmatter, for building a sidebar.
- **Islands** are `islands/<name>.tsx`, embedded with `<sluurp-island src="name">`. Only islands ship JavaScript.
- **Publishing:** `sluurp static --public ./site --out dist` exports static files for any host, islands included. Or run `sluurp serve` behind a TLS proxy.
- **Markdown sources** are served at each page's URL plus `.md`, and `/llms.txt` is generated from them, like this file.

## Start

- [Getting started](/docs/getting-started.md): Run Sluurp, make an administrator, serve a folder.
- [An app's shape](/docs/apps.md): The folders a Sluurp app is made of, and what each becomes.
- [Why SQLite](/docs/why-sqlite.md): Why an embedded database, what it costs, and how fast Sluurp is on it.

## Data

- [Collections and rules](/docs/collections.md): Real tables, and rules compiled into the SQL that reads them.
- [Browser client](/docs/client.md): sluurp.js, the client every page can import, and what each part of it does.
- [Rules](/docs/rules.md): The rules language, what a rule can name, and how rules on collections and fields are enforced.
- [REST API](/docs/api.md): The HTTP API every collection gets, with its filters, sorting, paging and errors.
- [OpenAPI and client generators](/docs/openapi.md): Your app's API as an OpenAPI 3.1 document, and how to get typed clients, docs and tests from it in any language.
- [Sign-in and users](/docs/auth.md): Accounts, passwords, sign-in links, providers, two-factor codes, invitations and who may do what.
- [Files and images](/docs/files.md): Uploads kept with their records, under their rules, and images resized on request.
- [Realtime](/docs/realtime.md): Every change to a collection as it happens, each row read as the person watching.
- [Sync](/docs/sync.md): Shapes of collections kept current in the browser over one WebSocket, in memory or SQLite.
- [History and AS OF](/docs/history.md): Every change kept, with who, when and why; any collection read as it stood.
- [Batches and reasons](/docs/batch.md): Several writes as one transaction, with a reason kept for each change.
- [Search by meaning](/docs/search.md): Rows found by what they mean rather than the words they use, with vectors kept in SQLite and nothing to set up.
- [Migrations](/docs/migrations.md): An app's data model and its data, versioned and run in order, as Flyway runs them.
- [Existing SQLite databases](/docs/attach.md): Use a database you already have, in place, as collections.

## Server

- [Functions and "use server"](/docs/server-functions.md): Endpoints in a folder, and functions written in a page that run on the server.
- [The server library](/docs/server-library.md): What server code has at hand, the web's standard globals and Sluurp's own, compared with Deno and Bun.
- [Hooks and events](/docs/hooks-and-events.md): Change a record before it is written, say what happened, and act on it elsewhere.
- [Scheduled jobs](/docs/jobs.md): Code that runs on a schedule, from an app's jobs/ folder.
- [Mail](/docs/mail.md): Send email from hooks, agents, jobs and server functions, through one mail server set up in the admin UI.
- [Server components and islands](/docs/server-components.md): routes/*.tsx and routes/*.md rendered on the server; islands where something moves.
- [Agents](/docs/agents.md): Code that watches a collection and acts on each change, with a model or without.
- [AI](/docs/ai.md): An optional language model, Claude or one on your own machine, for chat, drafting and agents.
- [Payments and billing](/docs/payments.md): A catalogue, charges and subscriptions, invoices, and payments online, by transfer or in cash.

## Frontend

- [The UI framework](/docs/ui-framework.md): JSX without React: components that run once, real DOM, and signals that update exactly what reads them. How it compares with React and Solid.
- [Styling and Tailwind](/docs/styling.md): Tailwind out of the box, with nothing to install or configure; theme tokens, your own CSS, and cn to join and merge classes.
- [UI kit](/docs/ui-kit.md): The components Sluurp ships, ready to import in any page.
- [Charts](/docs/charts.md): Charts written as a plain-English sentence or a few lines of JavaScript, and Plotly for everything else.
- [Pages](/docs/pages.md): A Notion-style editor any app can mount: blocks, folders, boards, forms and sign-ups.
- [Live views](/docs/live-views.md): Server-rendered views whose state stays on the server; the browser sends events and gets back only what changed.
- [Translations](/docs/translations.md): Every word of the app in every language it speaks, edited live in the page by translators working together.
- [Packages, bundles, budgets](/docs/vendoring.md): npm and JSR packages vendored as source, without package.json or node_modules; compared with npm, Node, Deno and Bun, and the limitations.
- [Hot reload](/docs/hot-reload.md): Save a file and the page changes in place, keeping what you were doing.

## Operations

- [Command line](/docs/cli.md): Every sluurp command, what it is for, and the options used most.
- [Admin UI](/docs/admin-ui.md): A dashboard for every collection, and for running the server, at /_/.
- [Admin extensions](/docs/admin-extensions.md): Your app's own screens, cards and actions in the admin, from an admin/ folder.
- [Deploying](/docs/deploying.md): Run Sluurp on a server, with HTTPS in front, backups and upgrades.
- [Static sites](/docs/static-sites.md): Publish an app as plain files, for GitHub Pages or any file host, with its islands still alive.
- [Security](/docs/security.md): What Sluurp does against the common attacks on web apps, and what is left to you.

## Development

- [Testing](/docs/testing.md): Tests of your whole app, written as Playwright writes them and run by Sluurp itself, in the admin or headless, with coverage.
- [Dev mode and production](/docs/dev-and-production.md): What Sluurp does while you develop, what it does in production, and how to choose.

## Pages

- [Business licence](/pricing.md)
- [Docs](/docs.md): Everything Sluurp does, and how to build on it.
- [Examples](/examples.md): The example apps in the repository, what each shows, and how to run it.
- [License](/license.md): Sluurp is free for non-commercial use. Commercial use needs a licence. Binaries only.
- [Showcase](/showcase.md): Sites and apps built with Sluurp, and how to add yours.
- [Terms of sale](/terms.md)