Key Concepts
BurgerAPI is a Bun-first, WinterCG-compatible framework for APIs and web apps. TypeScript and JavaScript are both first-class. Here are the main ideas.
File-based routing
Routes are defined by your file and folder structure. Put route.ts (or
route.js, route.mjs) files under your API directory (e.g. src/api), and
BurgerAPI maps them to URLs. Each route directory is self-contained with
optional sibling convention files: schema.ts, hooks.ts, openapi.ts,
config.ts. No manual route registration.
See File-Based Routing, Static API Routes, and Configuration.
Burger instance and configuration
You create one Burger instance with runtime options (apiDir,
apiPrefix, validation settings, and fallback OpenAPI metadata such as
title). Build-time concerns
(dirs, prefixes, debug) live in burger.build.ts and are used by the CLI
only. For WinterCG deployments you pass pre-built apiRoutes instead of
directories.
See Burger Class, Server Options, and Configuration.
Hooks and plugins
Hooks control the request lifecycle: onRequest, transform,
beforeRoute, afterRoute, mapResponse, onError. Global hooks live in
src/hooks.ts; route hooks in api/**/hooks.ts.
Plugins extend the application. They are registered in src/plugins.ts
with burger.usePlugin(plugin | factory, scope?, seed?), may package hooks,
and inject context values through transform (for example ctx.user or
ctx.apiKey). Providers are registered separately in src/providers.ts:
plugins cannot call provide(). Hooks and plugins are separate concepts.
Context
The single object flowing through the request lifecycle is BurgerContext
(ctx). It exposes the original request (ctx.request), parsed data
(ctx.query, ctx.params, ctx.json()), validated input (ctx.validated),
injected services (ctx.services), and more. Handlers always return a
standard Web Response.
Wrap a handler with defineRoute(schema, handler) to get ctx.validated
typed from the schema automatically, with no BurgerContext<typeof Schema>
generic to write by hand. defineHooks(schema, hooks) does the same for a
route's hooks.ts. Both are optional; the manual generic still works.
See Validation and Type Safety.
Validation
Request validation uses Standard Schema libraries, with Zod as the
default. Define per-method schemas in schema.ts for query, params, headers,
cookies, and body; BurgerAPI validates before your handler runs and attaches
the result to ctx.validated. Errors follow the RFC 9457 Problem Details
format.
See Zod Validation, Schema Definition, and Validation Errors.
OpenAPI
BurgerAPI can generate an OpenAPI 3.1 specification from your routes and schemas and serve an interactive docs UI.
See OpenAPI & Swagger.
CLI and builds
The Burger API CLI lets you create projects (create, with --lang ts|js),
add ecosystem hooks and plugins (add, list), run the dev server (dev),
and build for a deployment target (build --target=<platform>, start).
AOT route discovery means production builds never scan the filesystem at
runtime.
See CLI Tool and Build Command.
Deployment
burger-api build --target=<platform> generates the right output per
target: Bun (default) and Node.js get a self-contained bundle (app.serve()
on Bun, @burger-api/node-server's serve() on Node); Cloudflare Workers,
Deno, and Vercel get a portable export default { fetch: toFetchHandler(app) }
entry plus a scaffolded platform config (wrangler.toml / deno.json /
vercel.json), bundled by that platform's own tool. WebSocket routes work
natively on all of these except Vercel, which has no persistent-connection
model, so the build fails at build time rather than shipping a broken route.
See Deployment and Compatibility for the full per-runtime matrix.