BurgerAPI

BurgerAPI is a Bun-first TypeScript framework for building modern APIs, with file-based routing, inferred type safety, validation, WebSocket, plugins, and automatic OpenAPI. Build the same app for Bun, Node.js, Cloudflare Workers, Deno, or Vercel with one CLI flag.

Bun NativeMITOpen Sourcev1.0.0-betaBun 1.4.4+159stars

Get Started View on GitHub

import { Burger } from "burger-api";

const burger = new Burger({
  apiDir: "api",
});

burger.serve(4000);

import { defineRoute } from "burger-api";
import { GET as GetSchema } from "./schema";

export const GET = defineRoute(GetSchema, (ctx) => {
  return Response.json({
    message: "Hello from BurgerAPI",
  });
});

Why BurgerAPI

Everything you need to ship APIs

A focused toolkit for Bun backends: routing, validation, WebSocket, OpenAPI, and lifecycle hooks that work together out of the box.

Performance

Designed for the busy path

Parse only what you need, share structure across requests, and dispatch on the fastest matching strategy. Routes resolve through Bun's native router first, hook chains flatten once at boot, and validators are compiled once and cached.

Measured numbers live in burger-api-benchmarks, the dedicated repository that holds the harness, the methodology, and dated raw reports, so results can be reproduced rather than taken on faith.

Read the performance philosophy Benchmarks repository

Code

From file to endpoint in minutes

Three patterns you will use every day: start the server, define a route, and validate with Zod.

server.ts

import { Burger } from "burger-api";

const burger = new Burger({
  apiDir: "./src/api",
});

burger.serve(4000);

// api/products/[id]/schema.ts
import { z } from "zod";

export const GET = {
  params: z.object({ id: z.string().uuid() }),
};

export const PUT = {
  params: z.object({ id: z.string().uuid() }),
  body: z.object({
    name: z.string().min(1),
    price: z.number().positive(),
  }),
};

// api/products/[id]/route.ts
import { defineRoute } from "burger-api";
import { PUT as PutSchema } from "./schema";

export const PUT = defineRoute(PutSchema, (ctx) => {
  const { id } = ctx.validated.params;
  const { name, price } = ctx.validated.body;
  return Response.json({ id, name, price });
});

Developer Experience

Built for how you actually work

Fewer config files. Stronger types. Tools that stay out of your way until you need them.

File Routing

Routes that match your folders

Organize your API directory and BurgerAPI maps files to endpoints. Use [param] for dynamic segments and [...] for wildcards.

File → URL mapping

api/
├── route.ts                 →  GET /
├── users/
│   └── route.ts             →  GET /users
├── users/[id]/
│   └── route.ts             →  GET /users/:id
└── docs/[...]/
    └── route.ts             →  GET /docs/*

api/users/[id]/route.ts

// api/users/[id]/route.ts
import type { BurgerContext } from "burger-api";

export async function GET(ctx: BurgerContext) {
  const { id } = ctx.params;
  return Response.json({ id });
}

File-based routing docs

Validation

Zod schemas next to your routes

Export a schema per method in schema.ts. BurgerAPI validates before your code runs and puts typed data on ctx.validated, covering query, params, headers, cookies, and body. Share shapes between routes by importing a common schemas file, and validate responses too.

Validation guide

// api/posts/schema.ts
import { z } from "zod";

export const GET = {
  query: z.object({
    tag: z.string().optional(),
    limit: z.coerce
      .number()
      .min(1)
      .max(100)
      .default(10),
  }),
};

export const POST = {
  body: z.object({
    title: z.string().min(1),
    published: z.boolean().default(false),
  }),
};

// api/posts/route.ts
import { defineRoute } from "burger-api";
import { POST as PostSchema } from "./schema";

export const POST = defineRoute(PostSchema, (ctx) => {
  // Fully typed from the Zod schema above
  const { title, published } = ctx.validated.body;

  return Response.json(
    { title, published },
    { status: 201 }
  );
});

Lifecycle hooks

Compose auth, logging, and CORS

Six named hooks control every request: onRequest, transform, beforeRoute, afterRoute, mapResponse, and onError. Return a Response to short-circuit, or continue down the pipeline.

01Request

02onRequest

03transform

04Validation

05beforeRoute

06Handler

07afterRoute

08mapResponse

09Response

Request

onRequest

transform

Validation

beforeRoute

Handler

afterRoute

mapResponse

Response

onError steps in if any stage above throws

src/hooks.ts

// src/hooks.ts: global lifecycle hooks
import type { GlobalHooks } from "burger-api";

export const onRequest: GlobalHooks["onRequest"] = [
  () => {
    const id = crypto.randomUUID();
    // Forward hooks may return a response mapper. It wraps the final
    // response, so the header is set even when a later hook short-circuits.
    return (response: Response) => {
      const headers = new Headers(response.headers);
      headers.set("x-request-id", id);
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers,
      });
    };
  },
];

export const beforeRoute: GlobalHooks["beforeRoute"] = [
  (ctx) => {
    if (!ctx.headers.get("authorization")) {
      return Response.json(
        { error: "Unauthorized" },
        { status: 401 }
      );
    }
  },
];

export const afterRoute: GlobalHooks["afterRoute"] = [
  () => (response: Response) => {
    console.log(response.status, response.headers.get("x-request-id"));
    return response;
  },
];

Hooks docs

WebSocket

Real-time APIs with file-based WebSocket routes

Drop a ws.ts file under src/websocket/ and you get a live WebSocket route: open, message, and close handlers with decoded ws.params plus typed ws.data and ws.services. Dev auto-discovers src/websocket, and burger-api build reads the same default from burger.build.ts, so both agree out of the box (keep them in sync if you customize wsDir). Native support on Bun, Node.js, Cloudflare Workers, and Deno (Vercel has no persistent-connection model, so the build fails early instead of shipping a broken route).

WebSocket guide

src/websocket/chat/ws.ts

// src/websocket/chat/ws.ts
import type { BurgerWS } from "burger-api";

export function open(ws: BurgerWS) {
  ws.send(JSON.stringify({ type: "connected" }));
}

export function message(
  ws: BurgerWS,
  message: string | Buffer
) {
  // Echo the message back
  ws.send(message);
}

export function close(
  ws: BurgerWS,
  code: number,
  reason: string
) {
  // Connection closed
}

OpenAPI

Documentation that writes itself

Turn on OpenAPI once. BurgerAPI generates the specification and serves an interactive API explorer.

Generated from code

Routes and Zod schemas become an OpenAPI 3.0 document. No separate YAML to maintain.

Swagger UI included

Explore and try your API in the browser with the built-in Swagger UI.

Always in sync

When you change a schema or route, the OpenAPI document updates with your next run.

OpenAPI documentation

CLI

Scaffold and ship from the terminal

Create projects, add routes, run your API, and build it for any target: Bun, Node.js, Cloudflare Workers, Deno, or Vercel, all with one flag.

CLI reference

terminal

# Create a new project
bunx @burger-api/cli create my-api

# Scaffold a route
cd my-api
bunx @burger-api/cli generate route users

# Add an ecosystem hook (CORS)
bunx @burger-api/cli add cors

# Start the server
bun run dev

# Ship it: bun, node, cloudflare, deno, or vercel
burger-api build src/index.ts --target=cloudflare

Star us on GitHub

BurgerAPI is open source under the MIT license. Star the repo, open issues, and help shape the framework.

View Repository 159starsShow your support

Community

Build with the Bun community

Join discussions, contribute code, and stay up to date with releases.

Everything you need to ship APIs

File-Based Routing

Hybrid Router

Zod Validation

WebSocket

Plugins

Providers

Automatic OpenAPI

Lifecycle Hooks

TypeScript First

Bun Native

Deploy Anywhere

Lean by Design

Designed for the busy path

From file to endpoint in minutes

Built for how you actually work

Inferred Types

Bun Hot Reload

CLI Scaffolding

Colocated Schemas

Zero-Config OpenAPI

Clear Errors

Routes that match your folders

Zod schemas next to your routes

Compose auth, logging, and CORS

Real-time APIs with file-based WebSocket routes

Documentation that writes itself

Generated from code

Swagger UI included

Always in sync

Scaffold and ship from the terminal

Star us on GitHub

Build with the Bun community

Discussions

Contribute

Blog

Open Source

Designed for the busy path

From file to endpoint in minutes

Built for how you actually work

Inferred Types

Bun Hot Reload

CLI Scaffolding

Colocated Schemas

Zero-Config OpenAPI

Clear Errors

Routes that match your folders

Zod schemas next to your routes

Compose auth, logging, and CORS

Real-time APIs with file-based WebSocket routes

Documentation that writes itself

Generated from code

Swagger UI included

Always in sync

Scaffold and ship from the terminal

Star us on GitHub

Build with the Bun community

Discussions

Contribute

Blog

Open Source