Skip to main content

Welcome to BurgerAPI

BurgerAPI is a Bun-first, WinterCG-compatible framework for building modern APIs with file-based routing, end-to-end type safety, and a clear project structure. TypeScript and JavaScript are both first-class: the same conventions work with .ts, .js, and .mjs route files, and JavaScript projects get full JSDoc type-checking.

A new BurgerAPI

burger-api and @burger-api/cli 1.0.0-beta are rebuilt from the ground up and install by default. Please try them and open an issue if anything breaks or feels wrong. See the release notes for what is new. Coming from burger-api@0.9.7 or @burger-api/cli@0.9.9? The migration guide covers every breaking change.

What BurgerAPI is built around​

  • File-based routing: A route is a directory of sibling files.
  • Route convention files: route.ts, schema.ts, hooks.ts, openapi.ts, config.ts (self-contained; no group inheritance).
  • Hooks: Request lifecycle (onRequest, transform, beforeRoute, afterRoute, mapResponse, onError).
  • Plugins: Application extensions (src/plugins.ts). Hooks and plugins are separate concepts.
  • Providers: App services via src/providers.ts → ctx.services.
  • Validation: Standard Schema (Zod default) in schema.ts with per-method exports (GET, POST, …).
  • Context: Public type BurgerContext. Handlers return standard Web Response.
  • Type inference: defineRoute(schema, handler) / defineHooks(schema, hooks) infer ctx.validated from your schema, so there is no generic to write by hand.
  • OpenAPI: Spec + docs UI.
  • Ecosystem: ecosystem/hooks/, ecosystem/plugins/, ecosystem/skills/.
  • Build config: burger.build.ts is read by burger-api build, inspect, and doctor; burger-api dev/start read new Burger({...}) in src/index.ts. The scaffold keeps both in sync and the defaults agree out of the box. Runtime config lives in new Burger({...}), openapi.config.ts, plugins, and route config.ts.
  • Deploy targets: burger-api build --target=bun|node|cloudflare|deno|vercel: one command per platform, no hand-written entry files.

Getting started​

Core ideas​