# Keel

> The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.

Keel is a small, legible MVC framework for Node.js: a real service container,
service providers, dot-notation config, expressive routing, models, a queue, and
a code-generating console. Hono powers the HTTP layer; everything above it is Keel's.
Userland imports everything from `@shaferllc/keel/core`.

## Docs

- [Accounts](https://keeljs.com/docs/accounts): Password reset, email verification, and two-factor authentication — the flows every app with a login needs, built on primitives already in core (hash, encryption, mail, rate-limit).
- [Building Keel apps with AI](https://keeljs.com/docs/ai): Keel is built to be written with an AI agent.
- [API Resources](https://keeljs.com/docs/api-resources): apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — explicit, server-side, and composed from pieces you already have.
- [Architecture](https://keeljs.com/docs/architecture): Keel is small on purpose. This page maps the pieces and traces a request from socket to response. Nothing here is magic — every layer is a short, readable file in src/core/, and this guide is mostly a reading order for it.
- [Authentication](https://keeljs.com/docs/authentication): Session-based auth built on the pieces you already have: sessions hold the login, hashing checks passwords.
- [Authorization](https://keeljs.com/docs/authorization): Where authentication answers who you are, authorization answers what you're allowed to do.
- [Billing](https://keeljs.com/docs/billing): Keel Billing is a subscription-billing layer for charging customers, managing subscriptions, and reconciling gateway state through webhooks.
- [Broadcasting](https://keeljs.com/docs/broadcasting): Push events to clients in real time over named channels.
- [Service Broker](https://keeljs.com/docs/broker): Structure an application as services that talk to each other by name instead of by import.
- [Cache](https://keeljs.com/docs/cache): A small cache with TTLs and the remember pattern.
- [Configuration](https://keeljs.com/docs/configuration): Keel loads configuration from two sources: environment variables (.env) and config files (config/.ts).
- [The Console](https://keeljs.com/docs/console): Keel ships with a console for running the server and generating code.
- [The Service Container](https://keeljs.com/docs/container): The container is the backbone of Keel. Every service — config, the router, controllers, and anything you write — is registered in it and resolved out of it. It is the single registry every service resolves out of.
- [Controllers](https://keeljs.com/docs/controllers): Controllers are plain classes in app/Controllers/.
- [CORS](https://keeljs.com/docs/cors): Cross-Origin Resource Sharing lets browsers on other origins call your API.
- [Database](https://keeljs.com/docs/database): Keel ships a small, driver-agnostic query builder.
- [Debugging](https://keeljs.com/docs/debugging): Two helpers for the moments you'd otherwise reach for console.log.
- [Request Decorators](https://keeljs.com/docs/decorators): Attach named, computed values to the current request — request.user, request.tenant, request.locale — resolved lazily and memoized for the life of the request.
- [Errors & Exceptions](https://keeljs.com/docs/errors): Throw an exception anywhere — a handler, middleware, or a service deep in the container — and Keel's HTTP kernel turns it into the right response.
- [Events](https://keeljs.com/docs/events): A tiny event emitter for decoupling — fire an event in one place, handle it in another.
- [Factories & Seeders](https://keeljs.com/docs/factories): Populate the database with realistic fixtures for tests and demos.
- [Feature Flags](https://keeljs.com/docs/flags): Ship the code dark, turn it on when you're ready — per user, per team, or for everyone.
- [From install to deploy](https://keeljs.com/docs/from-install-to-deploy): One path from zero to a live Keel app — locally, on Cloudflare yourself, or on Keel Cloud with an AI agent.
- [Gates](https://keeljs.com/docs/gates): Keel Gates is a signup gate for private alpha / waitlist apps: an email allowlist, invite codes with use limits and expiry, and a single check that answers "may this person register?".
- [Getting Started](https://keeljs.com/docs/getting-started): Keel is a house framework for Node.js — a small, legible MVC layer over Hono.
- [Hashing & Encryption](https://keeljs.com/docs/hashing): Password hashing and value encryption, both built on the Web Crypto API — so they run identically on Node and the edge, with no native bindings (no bcrypt to compile).
- [Health Checks](https://keeljs.com/docs/health): Two endpoints, answering the two questions an orchestrator — Kubernetes, Fly, Railway, a load balancer — actually asks:
- [Helpers](https://keeljs.com/docs/helpers): Keel gives you a handful of global helper functions so you can reach the running application from anywhere — a route handler, a model, a plain function — without threading a container reference through every call.
- [Built on Hono](https://keeljs.com/docs/hono): Keel's HTTP layer is Hono — an ultrafast, web-standard router that runs on Node, Cloudflare Workers, Deno, Bun, and more.
- [Lifecycle Hooks](https://keeljs.com/docs/hooks): Tap into the application lifecycle — run code once the app is ready, clean up on shutdown, and observe route registration.
- [Hosting](https://keeljs.com/docs/hosting): Keel Hosting is a small toolkit for hosted Workers / D1 apps: a Cloudflare REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped secret encryption.
- [Internationalization](https://keeljs.com/docs/i18n): Translations with ICU message formatting, plus the Intl formatters that go with them.
- [Inertia](https://keeljs.com/docs/inertia): Keel ships a server-side Inertia.js adapter.
- [Keel Cloud (deploy from MCP)](https://keeljs.com/docs/keel-cloud): Keel Cloud hosts your Keel apps on .keeljs.cloud — preview and production Workers, D1, secrets vault, and full export (git + SQL).
- [Locks](https://keeljs.com/docs/locks): "Only one of you may do this at a time" — across processes, across nodes.
- [Logger](https://keeljs.com/docs/logger): A small leveled logger. It writes structured JSON by default — one line per event, ready for log aggregators — and pretty single-line output in debug. Reach it with the global logger() helper.
- [Mail](https://keeljs.com/docs/mail): Send email through a pluggable transport. Compose a message with a fluent builder and dispatch it — the API mirrors the database layer (setMailer / mail() are to mail what setConnection / db() are to the database). The core imports no SDK: the built-in transports use fetch, console, or memory, so it runs on Node and the edge.
- [Middleware](https://keeljs.com/docs/middleware): Middleware wraps every request, running code before and after your route handler.
- [Migrations](https://keeljs.com/docs/migrations): Version your database schema. A migration is a { name, up, down } object; a fluent schema builder describes tables, and the migrator runs them against your connection, tracking what's applied. The SQL is dialect-aware (sqlite / mysql / postgres) and the core imports no driver.
- [Models](https://keeljs.com/docs/models): Model is a tiny active-record layer over the query builder.
- [Notifications](https://keeljs.com/docs/notifications): Send a message to a recipient over one or more channels — mail, database, or your own — inline or through the queue.
- [OpenAPI](https://keeljs.com/docs/openapi): Keel OpenAPI generates an OpenAPI 3 spec from your routes and serves Swagger UI to explore it.
- [ORM](https://keeljs.com/docs/orm): Keel's ORM is a compact active record over the query builder: a model is a class pointed at a table, and its rows come back as typed objects with methods.
- [Packages](https://keeljs.com/docs/packages): A package is a redistributable slice of a Keel app — routes, a UI, config, migrations, console commands — that installs with a single app.register(...).
- [Pages](https://keeljs.com/docs/pages): Page-based routing — a file is a route.
- [Service Providers](https://keeljs.com/docs/providers): Service providers are the central place to configure your application.
- [Query Builder](https://keeljs.com/docs/query-builder): Keel's driver-agnostic query builder — build and run SQL by chaining methods off db(table).
- [Queues & Jobs](https://keeljs.com/docs/queues): Move slow work — sending mail, calling an API, processing an upload — off the request path.
- [Rate Limiting](https://keeljs.com/docs/rate-limiting): rateLimiter() is a middleware that caps how many requests a client can make in a window.
- [Redis](https://keeljs.com/docs/redis): A Redis integration built on a small pluggable driver — like the database and mail layers, the core imports no client, so it runs on Node and on the edge.
- [Request & Response](https://keeljs.com/docs/request-response): Beyond the terse param() / json() shortcuts, the request and response accessors give you the full input/output surface — no context threading.
- [Routing](https://keeljs.com/docs/routing): Routes live in routes/web.ts. The default export receives the Router and registers routes on it. The HTTP kernel later compiles them onto Hono.
- [Task Scheduling](https://keeljs.com/docs/scheduling): Declare recurring work with a fluent cadence, then let a single cron trigger drive it — a code-defined scheduler, edge-first.
- [Search](https://keeljs.com/docs/search): Full-text search over a pluggable driver — the same seam as the cache, queue, and storage layers, so the core imports no engine and runs on Node and the edge.
- [Securing SSR apps](https://keeljs.com/docs/security): Two middlewares harden server-rendered apps: securityHeaders() sets the defensive HTTP headers browsers act on, and csrf() blocks cross-site form submissions.
- [Sessions](https://keeljs.com/docs/sessions): Keel ships a cookie-backed session store. There's no external service to run, so it works the same on Node and on the edge. Session data lives in an HTTP-only cookie: the middleware reads it before your handler runs and writes it back afterward.
- [Social authentication](https://keeljs.com/docs/social-auth): "Sign in with GitHub / Google / Discord" — OAuth 2.0, without an SDK.
- [Starter kits](https://keeljs.com/docs/starter-kits)
- [Static Files](https://keeljs.com/docs/static-files): serveStatic() serves files from a directory (default public/) before your routes run.
- [Storage](https://keeljs.com/docs/storage): File storage over a pluggable disk — like the database and mail layers, the core imports no filesystem or SDK, so it runs on Node and the edge.
- [Teams](https://keeljs.com/docs/teams): Multi-tenancy, membership, roles, and invitations — where a row belongs to a team, and one team can never see another's.
- [Telemetry](https://keeljs.com/docs/telemetry): Distributed tracing — spans, W3C trace context, and an OTLP exporter — with no SDK.
- [Templates](https://keeljs.com/docs/templates): A string templating engine — {{ }} interpolation and @-prefixed tags for logic, includes, layouts, and components.
- [Testing](https://keeljs.com/docs/testing): Test your app by injecting requests — no server, no port, no network — and asserting on the response.
- [Transformers](https://keeljs.com/docs/transformers): A model knows the database; a transformer knows the API.
- [UI](https://keeljs.com/docs/ui): Keel ships a small design kit for server-rendered views: CSS tokens, named component styles, and Hono JSX components.
- [URL Builder](https://keeljs.com/docs/url-builder): Generate URLs from named routes so paths live in one place.
- [Validation](https://keeljs.com/docs/validation): validate() parses request input against a schema and returns typed data.
- [Views](https://keeljs.com/docs/views): Keel renders HTML with Hono JSX — type-safe components that run identically on Node and on Cloudflare Workers (no filesystem templating, so it ports anywhere).
- [Vite](https://keeljs.com/docs/vite): Wire a modern frontend build — bundling, hashed filenames, hot module reload — to Keel's server-rendered HTML, the way modern full-stack frameworks do.
- [Watch](https://keeljs.com/docs/watch): Keel Watch is a debug dashboard for Keel apps.

## Examples

Every topic has a runnable, type-checked example:

- [Accounts example](https://github.com/shaferllc/keel/blob/main/docs/examples/accounts.ts)
- [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
- [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
- [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)
- [Billing example](https://github.com/shaferllc/keel/blob/main/docs/examples/billing.ts)
- [Broadcasting example](https://github.com/shaferllc/keel/blob/main/docs/examples/broadcasting.ts)
- [Service Broker example](https://github.com/shaferllc/keel/blob/main/docs/examples/broker.ts)
- [Cache example](https://github.com/shaferllc/keel/blob/main/docs/examples/cache.ts)
- [Configuration example](https://github.com/shaferllc/keel/blob/main/docs/examples/configuration.ts)
- [The Console example](https://github.com/shaferllc/keel/blob/main/docs/examples/console.ts)
- [The Service Container example](https://github.com/shaferllc/keel/blob/main/docs/examples/container.ts)
- [Controllers example](https://github.com/shaferllc/keel/blob/main/docs/examples/controllers.ts)
- [CORS example](https://github.com/shaferllc/keel/blob/main/docs/examples/cors.ts)
- [Database example](https://github.com/shaferllc/keel/blob/main/docs/examples/database.ts)
- [Debugging example](https://github.com/shaferllc/keel/blob/main/docs/examples/debugging.ts)
- [Request Decorators example](https://github.com/shaferllc/keel/blob/main/docs/examples/decorators.ts)
- [Errors & Exceptions example](https://github.com/shaferllc/keel/blob/main/docs/examples/errors.ts)
- [Events example](https://github.com/shaferllc/keel/blob/main/docs/examples/events.ts)
- [Factories & Seeders example](https://github.com/shaferllc/keel/blob/main/docs/examples/factories.ts)
- [Gates example](https://github.com/shaferllc/keel/blob/main/docs/examples/gates.ts)
- [Hashing & Encryption example](https://github.com/shaferllc/keel/blob/main/docs/examples/hashing.ts)
- [Health Checks example](https://github.com/shaferllc/keel/blob/main/docs/examples/health.ts)
- [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
- [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
- [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
- [Hosting example](https://github.com/shaferllc/keel/blob/main/docs/examples/hosting.ts)
- [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
- [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
- [Locks example](https://github.com/shaferllc/keel/blob/main/docs/examples/locks.ts)
- [Logger example](https://github.com/shaferllc/keel/blob/main/docs/examples/logger.ts)
- [Mail example](https://github.com/shaferllc/keel/blob/main/docs/examples/mail.ts)
- [Middleware example](https://github.com/shaferllc/keel/blob/main/docs/examples/middleware.ts)
- [Migrations example](https://github.com/shaferllc/keel/blob/main/docs/examples/migrations.ts)
- [Models example](https://github.com/shaferllc/keel/blob/main/docs/examples/models.ts)
- [Notifications example](https://github.com/shaferllc/keel/blob/main/docs/examples/notification.ts)
- [OpenAPI example](https://github.com/shaferllc/keel/blob/main/docs/examples/openapi.ts)
- [ORM example](https://github.com/shaferllc/keel/blob/main/docs/examples/orm.ts)
- [Packages example](https://github.com/shaferllc/keel/blob/main/docs/examples/packages.ts)
- [Pages example](https://github.com/shaferllc/keel/blob/main/docs/examples/pages.ts)
- [Service Providers example](https://github.com/shaferllc/keel/blob/main/docs/examples/providers.ts)
- [Query Builder example](https://github.com/shaferllc/keel/blob/main/docs/examples/query-builder.ts)
- [Queues & Jobs example](https://github.com/shaferllc/keel/blob/main/docs/examples/queues.ts)
- [Rate Limiting example](https://github.com/shaferllc/keel/blob/main/docs/examples/rate-limiting.ts)
- [Redis example](https://github.com/shaferllc/keel/blob/main/docs/examples/redis.ts)
- [Request & Response example](https://github.com/shaferllc/keel/blob/main/docs/examples/request-response.ts)
- [Routing example](https://github.com/shaferllc/keel/blob/main/docs/examples/routing.ts)
- [Task Scheduling example](https://github.com/shaferllc/keel/blob/main/docs/examples/scheduling.ts)
- [Search example](https://github.com/shaferllc/keel/blob/main/docs/examples/search.ts)
- [Securing SSR apps example](https://github.com/shaferllc/keel/blob/main/docs/examples/security.ts)
- [Sessions example](https://github.com/shaferllc/keel/blob/main/docs/examples/sessions.ts)
- [Social authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/social-auth.ts)
- [Starter kits example](https://github.com/shaferllc/keel/blob/main/docs/examples/starter-kits.ts)
- [Static Files example](https://github.com/shaferllc/keel/blob/main/docs/examples/static-files.ts)
- [Storage example](https://github.com/shaferllc/keel/blob/main/docs/examples/storage.ts)
- [Teams example](https://github.com/shaferllc/keel/blob/main/docs/examples/teams.ts)
- [Telemetry example](https://github.com/shaferllc/keel/blob/main/docs/examples/telemetry.ts)
- [Templates example](https://github.com/shaferllc/keel/blob/main/docs/examples/templates.ts)
- [Testing example](https://github.com/shaferllc/keel/blob/main/docs/examples/testing.ts)
- [Transformers example](https://github.com/shaferllc/keel/blob/main/docs/examples/transformers.ts)
- [UI example](https://github.com/shaferllc/keel/blob/main/docs/examples/ui.tsx)
- [URL Builder example](https://github.com/shaferllc/keel/blob/main/docs/examples/url-builder.ts)
- [Validation example](https://github.com/shaferllc/keel/blob/main/docs/examples/validation.ts)
- [Views example](https://github.com/shaferllc/keel/blob/main/docs/examples/views.tsx)
- [Vite example](https://github.com/shaferllc/keel/blob/main/docs/examples/vite.ts)
- [Watch example](https://github.com/shaferllc/keel/blob/main/docs/examples/watch.ts)

## Optional

- [Full text of all docs](https://github.com/shaferllc/keel/blob/main/llms-full.txt): every guide concatenated into one file
- [AGENTS.md](https://github.com/shaferllc/keel/blob/main/AGENTS.md): conventions and workflow for AI agents editing a Keel app
- [README](https://github.com/shaferllc/keel/blob/main/README.md): project overview
- [Changelog](https://github.com/shaferllc/keel/blob/main/CHANGELOG.md): release history, newest first