Arachne framework guide

One framework for three kinds of project, built on Bun, signals and Standard Schema. Decisions: ADR 0015. Status and history: PROGRESS.md.

Start a project #

bunx @arachnejs/kit create my-site --template static   # pre-rendered site, no server
bunx @arachnejs/kit create my-app  --template server   # SSR + API + accounts
bunx @arachnejs/kit create my-api  --template api      # API only
cd my-app && bun install && bun run dev

What	Static	Server	API
Pages	pre-rendered HTML, hydrated, client routing	server-rendered, hydrated, client routing	—
Data	loaders run at build time → `_data/*.json`	loaders run per request	—
Deploy	`dist/` on any static host / CDN	`bun dist/server/index.js`	`bun dist/server/index.js`
Zero JS option	`hydrate: false`	—	—

How the pieces fit #

app/routes.tsx ──► @arachnejs/router (layouts, lazy routes, head, Link)
                    └─ @arachnejs/render + @arachnejs/jsx (compiled JSX, SSR + hydration, signals)
app/server.ts  ──► @arachnejs/server  (typed routes, validation, uploads, OpenAPI, MCP, middleware)
                    ├─ @arachnejs/schema   (one schema: validation, JSON Schema, OpenAPI, forms)
                    ├─ @arachnejs/db + db-sqlite + migrate
                    ├─ @arachnejs/auth + acl  (accounts, sessions, tokens, 2FA, groups, permissions)
                    ├─ @arachnejs/mailer   (SMTP, Resend, dev console)
                    └─ @arachnejs/storage  (disk, S3/R2/MinIO)
arachne.config.ts ─► @arachnejs/kit  (dev server + hot reload, builds, prerendering, CLI)

Guides by task #

Task	Where
Pages, layouts, links, titles	router README, kit: Pages
Page data (loaders), prerendering dynamic routes	kit: Server
API routes, validation, uploads, errors	server README
Schemas, coercion, cross-field rules	schema README
OpenAPI docs and the typed client	server: OpenAPI
Sign-up, login, reset, 2FA, API tokens, blocking	auth README
Groups, permissions, ownership rules	acl README
Database queries, transactions	db README
Schema changes	migrate README, `arachne migrate`
Email	mailer README
File storage	storage README
UI components	UI docs
Dev server, builds, deploy, CLI	kit README

Agents (MCP) #

Every package exports an MCP module (bun run mcp serves them all). Apps can expose their own API routes as MCP tools: mark routes mcp: true and set mcp in arachne.config.ts; calls run through the same validation, auth and permission checks as HTTP requests.

Security defaults #

CSP with per-request nonces, HSTS, nosniff, frame and referrer policies.
Validation on every declared input; 422 with issue paths.
Parameterised SQL only; update/delete refuse to run without where.
argon2id passwords, hashed session and API tokens, __Host- cookies, CSRF via Origin / Fetch Metadata, lockout, rate limits, audit events.
Safe upload keys; downloads with RFC 6266 Content-Disposition and nosniff.

API reference #

Every exported symbol has TSDoc (bun run docs:check keeps it that way); editors show it on hover. Package READMEs are the task-oriented reference.