# Beignet

> Contract-first TypeScript framework for building type-safe REST APIs with typed servers, clients, validation, and OpenAPI.

These docs cover Beignet, a contract-first TypeScript framework for building REST APIs, typed clients, validated application workflows, and provider-backed infrastructure with end-to-end type safety. The full extracted text of every page is available in one file at https://www.beignetjs.com/llms-full.txt.

## Start

- [Beignet](https://www.beignetjs.com/): Contract-first TypeScript framework for building type-safe REST APIs with typed servers, clients, validation, and OpenAPI.
- [Quickstart](https://www.beignetjs.com/getting-started): Create a Beignet app, run it locally, and make a first schema change you can watch take effect across the form, API, and OpenAPI.
- [Mental model](https://www.beignetjs.com/concepts): A glossary of the Beignet vocabulary: contracts, route groups, use cases, ports, providers, hooks, policies, errors, and the API grammar.
- [Build your first feature](https://www.beignetjs.com/build-first-resource): Generate a Beignet resource, read the generated contract, use case, and port, then follow one real change from schema to database.
- [App architecture](https://www.beignetjs.com/app-architecture): Understand the Beignet app architecture: where contracts, routes, use cases, ports, infra, clients, and features belong.
- [Comparisons](https://www.beignetjs.com/comparisons): How Beignet compares to tRPC, ts-rest, oRPC, Hono, NestJS, AdonisJS, and Laravel-style frameworks — and when each is the better choice.

## Core app model

- [Contracts](https://www.beignetjs.com/contracts): Define Beignet API contracts for methods, paths, parameters, responses, errors, metadata, and schema validation.
- [Use cases](https://www.beignetjs.com/application): Build validated Beignet use cases with input and output schemas, domain events, instrumentation, and route-handler wiring.
- [Ports and adapters](https://www.beignetjs.com/ports): Define dependency ports for Beignet application code so handlers and use cases stay independent from infrastructure.
- [Routes and server](https://www.beignetjs.com/server): Create Beignet servers with typed route handlers, request and response validation, lifecycle hooks, and runtime adapters.
- [Request lifecycle](https://www.beignetjs.com/request-lifecycle): Follow a Beignet request through route matching, parsing, hooks, context, handlers, validation, errors, and response ownership.
- [Hooks](https://www.beignetjs.com/hooks): Use Beignet server hooks for auth, CORS, logging, tracing, rate limits, response shaping, and error mapping.
- [Errors](https://www.beignetjs.com/errors): Handle Beignet server and client errors with AppError, ContractError, structured response envelopes, and safeCall.
- [Clients](https://www.beignetjs.com/client): Create fully typed Beignet HTTP clients from your contracts with typed params, responses, errors, and safe calls.
- [OpenAPI](https://www.beignetjs.com/openapi): Generate OpenAPI 3.1 documents from Beignet contracts, operation metadata, responses, parameters, and Zod schemas.

## Feature design

- [Domain modeling](https://www.beignetjs.com/domain): Use Beignet domain helpers for value objects, entities, domain events, and validated domain modeling.
- [Authentication](https://www.beignetjs.com/authentication): Authenticate Beignet requests with auth ports, route metadata, HTTP boundary hooks, and Better Auth.
- [Authorization](https://www.beignetjs.com/authorization): Keep Beignet authorization in use cases and app-owned policy functions so business rules run from HTTP, jobs, scripts, and tests.
- [Config](https://www.beignetjs.com/config): Define environment-first Beignet configuration with schema validation, prefix filtering, typed values, and testable config loading.
- [Testing](https://www.beignetjs.com/testing): Test Beignet apps at the use-case, route, contract, provider, seed, and resource boundaries.

## Frontend adapters

- [React overview](https://www.beignetjs.com/react): Choose Beignet React integrations for server state, URL state, and forms while reusing contract schemas and types.
- [React Query](https://www.beignetjs.com/react-query): Create typed TanStack Query options, mutations, query keys, cancellation, and prefetching from Beignet contracts.
- [React Hook Form](https://www.beignetjs.com/react-hook-form): Create typed React Hook Form options from Beignet request body schemas and reuse contract validation in forms.
- [React uploads](https://www.beignetjs.com/react-uploads): Track Beignet upload client state from React components with typed metadata, progress, errors, and completion results.
- [nuqs](https://www.beignetjs.com/nuqs): Connect Beignet query schemas to nuqs URL state for typed search, filters, tabs, sorting, and pagination.

## Infrastructure

- [Providers](https://www.beignetjs.com/providers): Install Beignet provider adapters for databases, caches, mail, auth, logging, jobs, rate limits, and event buses.
- [Database and transactions](https://www.beignetjs.com/database): Use Beignet repository ports, Drizzle adapters, Unit of Work transactions, and after-commit domain events in production apps.
- [Cache](https://www.beignetjs.com/cache): Use Beignet's CachePort with Redis or app-owned adapters for cached reads, invalidation, and typed serialization.
- [Storage](https://www.beignetjs.com/storage): Use Beignet's StoragePort for object storage, generated files, imports, exports, attachments, and public asset URLs.
- [Uploads](https://www.beignetjs.com/uploads): Define typed upload workflows with file constraints, authorization, direct upload signing, completion hooks, and storage-backed objects.
- [Mail](https://www.beignetjs.com/mail): Send mail through Beignet's stable MailerPort with Resend, SMTP, memory test adapters, jobs, and devtools.
- [Rate limiting](https://www.beignetjs.com/rate-limiting): Protect Beignet routes with contract metadata, rate limit hooks, and Upstash-backed RateLimitPort adapters.

## Background work

- [Workflows](https://www.beignetjs.com/workflows): Map Beignet's background work toolbox: events, jobs, schedules, tasks, notifications, idempotency, and outbox, and how they compose into workflows.
- [Events](https://www.beignetjs.com/events): Define Beignet domain events, listeners, event buses, and after-commit publishing.
- [Jobs](https://www.beignetjs.com/jobs): Define typed Beignet jobs, dispatch them locally or durably, and run them through provider adapters such as Inngest.
- [Schedules](https://www.beignetjs.com/schedules): Define typed Beignet schedules for cron-triggered workflows, inline testing, and job dispatch.
- [Idempotency](https://www.beignetjs.com/idempotency): Make Beignet commands, webhooks, and jobs safe to retry with scoped keys, payload fingerprints, and durable reservations.
- [Outbox](https://www.beignetjs.com/outbox): Record Beignet events and jobs transactionally, then drain them after commit with retries and dead-letter handling.
- [Notifications](https://www.beignetjs.com/notifications): Define user-facing Beignet notifications above mail, jobs, events, and outbox-backed delivery.
- [Tasks](https://www.beignetjs.com/tasks): Define typed Beignet operational tasks for backfills and maintenance, register them in server/tasks.ts, and run them with beignet task run.

## Observability

- [Logging](https://www.beignetjs.com/logging): Add structured logging to Beignet apps with LoggerPort, request hooks, Pino, request IDs, and production-safe metadata.
- [Error reporting](https://www.beignetjs.com/error-reporting): Report Beignet HTTP, job, schedule, outbox, and task failures through app-owned ports and production alerting workflows.
- [Audit and activity logging](https://www.beignetjs.com/audit): Record durable Beignet audit logs with actor, tenant, request, resource, and transaction-aware activity metadata.
- [Devtools](https://www.beignetjs.com/devtools): Use Beignet devtools to inspect development-time request, error, use case, job, schedule, and provider events.

## Going to production

- [Going to production](https://www.beignetjs.com/deployment): Take a Beignet app to production: preflight checks, env validation and secrets, host settings, runtime entrypoints, and the pre-launch security checklist.
- [Privacy lifecycle](https://www.beignetjs.com/privacy-lifecycle): Design Beignet app retention, export, deletion, anonymization, redaction, and sensitive-data boundaries before production launch.

## Reference

- [CLI](https://www.beignetjs.com/cli): Use the Beignet CLI to create apps, generate features, inspect routes, and keep projects aligned.
- [Packages and imports](https://www.beignetjs.com/package-reference): Map Beignet app responsibilities to the core subpaths, integration packages, providers, and tooling that implement them.
- [Coding agents](https://www.beignetjs.com/agents): Point coding agents at Beignet: the scaffolded AGENTS.md and CLAUDE.md guides, the beignet mcp server and its tools, and the llms.txt index for the docs.
- [Stability and releases](https://www.beignetjs.com/stability): What Beignet's 0.0.x alpha line means in practice: lockstep versioning, the CI gates every release passes, and what will gate 1.0.
- [Writing a provider](https://www.beignetjs.com/writing-a-provider): Build a Beignet provider package: ports, lifecycle, instrumentation, metadata manifest, and conventions.
- [API reference](https://www.beignetjs.com/api-reference): Open the generated Beignet API reference built from public TypeScript exports and TSDoc comments.

## Optional

- [llms-full.txt](https://www.beignetjs.com/llms-full.txt): Full extracted text of every documentation page in a single file.
- [API reference](https://www.beignetjs.com/api-reference): Generated TypeDoc API reference for the published Beignet packages.