stonewareDocumentation
Everything, in 31 pages
Stoneware is small on purpose. If a page here feels long, that is a bug in the page rather than a sign of depth.
Source, issues and releases: stoneware-dev/stoneware-core
What it solves
The specific problems Stoneware exists for — and the ones it does not.
Quick start
Scaffold a project, run it, and understand what the two directories mean.
What gets generated
Every file create-stoneware writes, what it is for, and what a build adds.
How it works
The path a request takes, and what hydration does to the DOM.
Routing
File-based, Next.js-style conventions resolved by Bun's own router.
Components
Plain functions that compose, take children and nest — and the one rule about async that follows from rendering to a string.
Islands
How a component earns its JavaScript, and what hydration actually does.
When islands hydrate
client:visible, client:idle and client:media — and what a page stops downloading.
Head and images
Per-page metadata, and an <Image> that fixes layout shift without a build pipeline.
SEO and sharing
What a Stoneware site does for search before you configure anything, and the one call that writes the rest of the head.
Styling
Co-located CSS, collected by the build, with no import and no link tag to maintain.
Error pages
Custom 404 and 500 pages, and the three properties that hold whether or not you write them.
Error boundaries
Lose one subtree instead of the whole page, without losing the error.
Server actions
Form handling where CSRF verification is structural, not a decorator.
Middleware and APIs
One file that runs on every request, and what changed for API routes.
Databases
Where db.ts goes, where queries run, and the one place they must never.
Testing
Request in, HTML out — with no port opened, no server started and nothing to tear down.
Security defaults
What is on before you configure anything, and why it cannot be off by accident.
CLI and builds
Dev server, production build, and what each command actually emits.
Deploying
A checklist, one decision, and a walkthrough per platform — server or static, Vercel or Cloudflare.
Caching
What every response tells a browser and a CDN, why a page is never cached on the server, and the header that keeps a shared cache from handing one visitor another's page.
Static export
Prerender the whole site to files any host can serve, and know exactly which pages cannot go.
Configuration
Every option in stoneware.config.ts, its default, and the environment variable that overrides it.
API reference
Everything the package exports, what it is for, and which of them you are unlikely to need.
Benchmark
Two studies: what the server does on 0.2.0, and what a visitor's browser waits for. One named run each, with what varies between runs called out.
What's new
0.2.0 — a sitemap you do not maintain by hand, serving from more than one process, shared-cache safety, and several silent failures that now say something.
v0.1.8
The client chunks finally reach a deployed site, and a URL can no longer make the server answer 500.
v0.1.7
Error attribution, a CSP that extends, and an export that checks its own links.
v0.1.6
Error boundaries, a request hook, a request path about three times faster, and a dev server that stopped breaking itself.
v0.1.4 & v0.1.5
The two deploy releases — why a build would not run where it was not built.
Past releases
What shipped in 0.1.3 and 0.1.2, and what each change replaced.