Quickstart

Create a Beignet app, run it, inspect the routes, then open the files that own each production concern.

Create an app

bunx -p @beignet/cli beignet create my-app
cd my-app
bun install
cp .env.example .env.local
bun run dev

Open http://localhost:3000 for the starter UI, http://localhost:3000/api/health for the health check, and http://localhost:3000/api/devtools while developing.

Inspect the app

Run these from the starter app:

bunx -p @beignet/cli beignet routes
bunx -p @beignet/cli beignet lint
bunx -p @beignet/cli beignet doctor
bun run typecheck

routes confirms which contracts are wired to route files. lint checks that feature layers do not import runtime, UI, or infrastructure code in the wrong direction. doctor checks for route, OpenAPI, and resource drift. typecheck verifies that route handlers, use cases, ports, clients, and tests still agree with the contracts.

Open these files first

File or folder	Why it matters
`features/todos/contracts.ts`	Source of truth for typed clients, server validation, OpenAPI, and React helpers
`features/todos/routes.ts`	Feature route group that maps contracts to use cases
`features/todos/use-cases/`	Application behavior and validation
`features/todos/components/`	Starter UI for the todo workflow
`server/routes.ts`	Central route registry and OpenAPI contract list
`server/index.ts`	Context, providers, hooks, and error mapping
`app/api/`	Thin Next.js route files that expose the central server handler
`ports/index.ts`	App-owned dependency interfaces
`infra/app-ports.ts`	Default runtime wiring for those ports
`lib/env.ts`	Validated deployment configuration

Read App architecture when you want the full map.

Generate the next feature

Use make resource when a feature needs the full Beignet path from contract to tests:

bunx -p @beignet/cli beignet make resource projects

That command writes features/projects/contracts.ts, features/projects/use-cases/, features/projects/ports.ts, an in-memory infra adapter, a feature route group, and tests for a new resource. Read Build your first resource for the walkthrough.

In apps created with the drizzle-turso integration, it also writes a Drizzle table and durable repository adapter, then registers them in the central repository factory.

Use narrower generators when you only need one layer:

bunx -p @beignet/cli beignet make contract projects
bunx -p @beignet/cli beignet make use-case projects/archive-project
bunx -p @beignet/cli beignet make port search
bunx -p @beignet/cli beignet make adapter search

Run beignet lint and beignet doctor after manual edits. Beignet is most useful when its conventions stay inspectable.