# Oven

> A batteries-included backend framework for Bun. Infrastructure — auth, database, mail,
> storage, queues — is configuration rather than wiring: add a brick, get a feature, fully typed.

Oven is TypeScript-native and Bun-only. Routes are files, validation is
[Standard Schema](https://standardschema.dev) so Zod and Valibot both work, errors are RFC 9457
problem+json, and an OpenAPI 3.1 document is generated from the same schemas that validate.

Key things to know before writing code:

- Handlers **return values**. There is no `res`, no `res.json()`, no `next()`.
- Errors are thrown: `throw new NotFound('...')`. They become problem+json.
- `ctx.db` is the **native** ORM client — a Drizzle instance, a Mongoose connection — not a
  wrapper. There is no Oven query API to learn.
- Bricks contribute to the context. Leaving one out makes using it a compile error.
- Express middleware does not work here. Oven middleware is `(ctx, next) => Response`.


## Start here

- [Installation](https://theoven.app/docs/start/installation/): Get Oven running on Bun in under a minute.
- [Batteries included](https://theoven.app/docs/start/batteries/): What you no longer install, wire, order, or forget — and what it costs when you do not use it.
- [Philosophy](https://theoven.app/docs/start/philosophy/): Why Oven makes the choices it makes.

## Tutorial

- [1. Your first route](https://theoven.app/docs/tutorial/first-route/): Create an Oven app, register a route, and understand the context object.
- [2. Validation](https://theoven.app/docs/tutorial/validation/): One declaration that validates the request, types the handler, and will document the endpoint.
- [3. Errors](https://theoven.app/docs/tutorial/errors/): Throw an error, get a correct HTTP response — synchronously or not.
- [4. A database](https://theoven.app/docs/tutorial/database/): Add a brick, get a typed client on the context — and keep writing ordinary Drizzle.
- [5. Auth](https://theoven.app/docs/tutorial/auth/): Signup, login and guarded routes — eight endpoints you do not write.

## Guides

- [Benchmarks](https://theoven.app/docs/guides/benchmarks/): Numbers you can reproduce, including the ones where we lose.
- [Coming from Express](https://theoven.app/docs/guides/coming-from-express/): A translation guide — deliberately not a compatibility layer.
- [Deployment](https://theoven.app/docs/guides/deployment/): Build it, put it in a container, and know what to check before you call it done.
- [Testing](https://theoven.app/docs/guides/testing/): Test an Oven app the way a client uses it — no server, no port, no mocks.
- [Writing your own brick](https://theoven.app/docs/guides/writing-a-brick/): Add a capability to the request context, fully typed, in about fifty lines.

## Bricks — add one, get a feature

- [Brick catalogue](https://theoven.app/docs/bricks/): Every brick Oven ships — what it does, what it adds, and whether it is built yet.
- [openapi](https://theoven.app/docs/bricks/openapi/): Serves an OpenAPI 3.1 document and a browsable reference, generated from the schemas your routes already declare.
- [db](https://theoven.app/docs/bricks/db/): The database contract — connect, health, close, transactions. Your queries stay native.
- [db-drizzle](https://theoven.app/docs/bricks/db-drizzle/): Drizzle ORM over bun:sqlite, Postgres and MySQL — the default database for Oven.
- [db-mongoose](https://theoven.app/docs/bricks/db-mongoose/): MongoDB through Mongoose, on the same database contract as Drizzle.
- [auth](https://theoven.app/docs/bricks/auth/): The auth contract — identity, route guards, named policies, and the flows every storage brick shares.
- [auth-basic](https://theoven.app/docs/bricks/auth-basic/): Email and password auth that works out of the box — signup, login, refresh, logout, password change and reset.
- [auth-mongo](https://theoven.app/docs/bricks/auth-mongo/): The auth-basic flows, stored in MongoDB with Mongoose.
- [auth-clerk](https://theoven.app/docs/bricks/auth-clerk/): Clerk-hosted sign-in, verified on every request. No routes, no sessions to manage.
- [auth-better](https://theoven.app/docs/bricks/auth-better/): better-auth mounted in Oven — it brings its own routes, sessions and plugins.
- [mail](https://theoven.app/docs/bricks/mail/): Transactional email — console and memory drivers included, a real provider when you configure one.
- [storage](https://theoven.app/docs/bricks/storage/): Object storage on S3, R2, MinIO or Spaces — with a local directory for development, so uploads work before you have a bucket.
- [queue](https://theoven.app/docs/bricks/queue/): Background jobs with retries, backoff, a dead letter and cron — in memory, in Redis, or in the Postgres you already run.
- [cache](https://theoven.app/docs/bricks/cache/): Caching with tag invalidation and stampede protection — in memory, or in Redis.
- [telemetry](https://theoven.app/docs/bricks/telemetry/): OpenTelemetry tracing — spans named by route, context propagation, and logs you can get back to a trace from.
- [storage-bunny](https://theoven.app/docs/bricks/storage-bunny/): Bunny.net Storage as a driver for the storage brick — cheap egress through pull zones, signed delivery URLs.
- [storage-imagekit](https://theoven.app/docs/bricks/storage-imagekit/): ImageKit as a storage driver, plus the transformation URLs that are the reason to use it.
- [webhooks](https://theoven.app/docs/bricks/webhooks/): Inbound webhooks verified before your handler runs — Stripe, GitHub, Slack, Svix, Razorpay and Shopify.
- [ratelimit](https://theoven.app/docs/bricks/ratelimit/): Rate limiting that counts across every instance, in Redis or Postgres, with a sliding window.
- [vector](https://theoven.app/docs/bricks/vector/): Vector search behind one contract — an embedded scan, pgvector, or Qdrant, with the same score on all three.
- [ai](https://theoven.app/docs/bricks/ai/): Everything around an AI SDK call — SSE streaming, abort on disconnect, caching, token accounting and budgets.
- [image](https://theoven.app/docs/bricks/image/): Resize, convert and guard uploads on Bun.Image — no native module, and a decompression bomb refused in under a microsecond.

## Reference

- [App](https://theoven.app/docs/reference/app/): createApp, route registration, configuration, and the server lifecycle.
- [Context](https://theoven.app/docs/reference/context/): The single argument every handler receives — request, response, and whatever your bricks contributed.
- [File-based routing](https://theoven.app/docs/reference/file-routing/): The filesystem is the route table.
- [Routers](https://theoven.app/docs/reference/routers/): Group routes, mount them anywhere, and share a prefix, tags and an auth requirement across them.
- [Validation](https://theoven.app/docs/reference/validation/): One declaration that validates the request, types the handler, and documents the endpoint.
- [Dependencies](https://theoven.app/docs/reference/dependencies/): Per-request, per-route values — composable, cached within a request, with teardown and a testing seam.
- [Errors](https://theoven.app/docs/reference/errors/): Throw an error, get a correct HTTP response — as RFC 9457 problem+json, synchronously or not.
- [Middleware & hooks](https://theoven.app/docs/reference/middleware/): Onion-model middleware, five lifecycle hooks, and the built-ins that ship configured.
- [Always-on batteries](https://theoven.app/docs/reference/batteries/): Body parsing, uploads, cookies, token capture and query parsing — with nothing to install.
- [Writing a brick](https://theoven.app/docs/reference/bricks/): The brick contract — how a brick contributes a capability, and how its types reach the context.
- [Environment variables](https://theoven.app/docs/reference/env/): Reading them safely, and validating them at boot.
- [CLI](https://theoven.app/docs/reference/cli/): Scaffold, run, build and inspect Oven apps.
- [WebSockets & SSE](https://theoven.app/docs/reference/realtime/): Real-time, upgraded from an ordinary route — so guards, params and validation all still apply.
- [The public API](https://theoven.app/docs/reference/public-api/): What each package exports, what is deliberately not exported, and why the difference matters to you.

## Other

- [Build a todo API](https://theoven.app/docs/build/): A guided project — from an empty directory to an authenticated, tested, documented API. Every snippet is real code from a working app.
- [Projects](https://theoven.app/docs/projects/): Three realistic backends, built end to end — a chat app, a Trello clone, and a video platform.
- [Recipes](https://theoven.app/docs/recipes/): Short, self-contained builds — sign in with Google, upload images, share files, go real-time.
- [1. Set it up](https://theoven.app/docs/build/setup/): One command, and a tour of what you get before writing a line.
- [Chat: what you will build](https://theoven.app/docs/projects/chat/): A chat backend with rooms, membership, message history and live delivery.
- [Sign in with Google](https://theoven.app/docs/recipes/google-login/): A working Google sign-in, from an empty app to a signed-in user, including the console setup everyone gets wrong.
- [Trello: what you will build](https://theoven.app/docs/projects/trello/): Boards, lists and cards — with permissions that are named, and ordering that survives drag-and-drop.
- [YouTube: what you will build](https://theoven.app/docs/projects/youtube/): Channels, an upload pipeline, playlists, subscriptions and a feed — the whole backend.
- [2. The first endpoint](https://theoven.app/docs/build/first-endpoint/): A route file, a schema, and why the filesystem is the router.
- [Chat: the schema](https://theoven.app/docs/projects/chat/schema/): Three tables, and the two indexes that decide whether history stays fast.
- [Image uploads](https://theoven.app/docs/recipes/image-uploads/): Accept an avatar, validate it before your code runs, store it, and serve it back.
- [Trello: schema and permissions](https://theoven.app/docs/projects/trello/schema/): Five tables, three roles, and permissions that have names instead of being scattered through handlers.
- [YouTube: channels and accounts](https://theoven.app/docs/projects/youtube/channels/): A channel per account, handles that cannot collide, and Google sign-in dropped in.
- [3. Storing todos](https://theoven.app/docs/build/storing-todos/): A table, a migration, and the three routes that write to it.
- [Chat: rooms and membership](https://theoven.app/docs/projects/chat/rooms/): Create a room, join one, and write the check that every other route depends on.
- [Share a file with a link](https://theoven.app/docs/recipes/file-sharing/): Upload a file, get a link that expires, and have the file clean itself up afterwards.
- [Trello: lists and cards](https://theoven.app/docs/projects/trello/cards/): The straightforward half — creating lists and cards, and reading a board in one query.
- [YouTube: the upload pipeline](https://theoven.app/docs/projects/youtube/uploading/): A video that is honestly not watchable yet, and a background job that makes it so.
- [4. Locking it down](https://theoven.app/docs/build/auth/): Signup, login, and scoping every query to its owner — the chapter that matters.
- [Chat: messages and pagination](https://theoven.app/docs/projects/chat/messages/): Send a message, and page backwards through history without showing anyone the same message twice.
- [Real-time notifications](https://theoven.app/docs/recipes/realtime/): Push updates to a signed-in user over a WebSocket that is guarded by the same auth as everything else.
- [Trello: ordering that survives dragging](https://theoven.app/docs/projects/trello/ordering/): Move a card by writing one row — and the measured point at which that stops working.
- [YouTube: watching and visibility](https://theoven.app/docs/projects/youtube/watching/): One visibility rule used by four routes, and a view count that is not trivially inflatable.
- [5. Testing it](https://theoven.app/docs/build/testing/): No server, no port, no mocks — and the tests that matter most.
- [Chat: live delivery](https://theoven.app/docs/projects/chat/realtime/): A socket that refuses non-members before it opens, and a broadcast that does not walk a list.
- [Trello: activity and shipping](https://theoven.app/docs/projects/trello/activity/): An audit trail written in the same transaction as the change, and what to fix before deploying.
- [YouTube: playlists](https://theoven.app/docs/projects/youtube/playlists/): Ordered collections, reusing the positions from Trello — and the visibility trap they introduce.
- [6. Shipping it](https://theoven.app/docs/build/shipping/): What production refuses to boot with, and why each refusal exists.
- [YouTube: subscriptions and the feed](https://theoven.app/docs/projects/youtube/subscriptions/): Subscribe, count subscribers, and build a home feed that is one query however many channels someone follows.
- [Oven on Bun 1.4](https://theoven.app/docs/blog/oven-on-bun-1-4/): We moved the whole monorepo to Bun 1.4, shipped an image brick built on Bun.Image, and re-ran the benchmarks — including the one that now says something we would rather it did not.
- [Oven documentation](https://theoven.app/docs/): The batteries-included Bun framework — guides, tutorial and API reference.

## Full text

- [Everything above, in full](https://theoven.app/llms-full.txt)