Skip to main content

Installation

BurgerAPI is built for the Bun.js runtime. Make sure you have Bun installed before you begin.

Prerequisites​

  • Bun: Follow the official Bun installation guide to install it on your system.

    You can verify your installation by running:

    bun --version

Burger API comes with a powerful CLI tool that makes it easy to scaffold new projects and manage hooks and plugins. Install it globally to get started:

Installation​

# Global installation
bun add -g @burger-api/cli

Or use with bunx (No Installation Needed):

bunx @burger-api/cli create my-project

Option 2: Standalone Executable (Alternative Installation Method)​

  • macOS/Linux/WSL: 
    curl -fsSL https://burger-api.com/install.sh | bash
  • Windows PowerShell: 
    irm https://burger-api.com/install.ps1 | iex

Option 3: Download a binary from GitHub Releases​

  1. Download the executable for your platform from GitHub Releases.

  2. Add the downloaded file to your PATH.

  3. On Linux and macOS, make it executable:

    chmod +x burger-api

Create your project​

Once installed, you can create a new project by running:

burger-api create my-awesome-api

Run your project​

cd my-awesome-api
bun run dev

For detailed CLI usage, check out the CLI Tool Guide.

Update to the latest version​

Getting an error?

Update the CLI and the framework to the latest version first. Most problems are already fixed there.

  • Installed with Bun: this replaces the old version.

    bun add -g @burger-api/cli@latest

  • Installed with the install script: run the same script again. It removes old versions first (a global @burger-api/cli from Bun or npm, and the previous executable), then installs the latest one.

  • The framework in your project:

    bun add burger-api@latest

Run burger-api --version to check which version you have. If it still shows an old version, another burger-api comes first on your PATH: remove it, or run the install script, which tells you where it is.

Alternative: Manual Setup (Standard Bun)​

If you prefer not to use the CLI, you can set up a project manually using standard Bun commands:

  1. Initialize a new Bun project: Navigate to your project directory and run:

    bun init

    Follow the prompts to create a basic Bun project.

  2. Install BurgerAPI and Zod:

    bun add burger-api zod

  3. Create your entry file (src/index.ts):

    src/index.ts
    import { Burger } from "burger-api";

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

    const port = Number(process.env.PORT) || 4000;
    app.serve(port, () => {
      console.log(`Server running on http://localhost:${port}`);
    });

  4. Create your first route. The runtime reads validation from a route's schema.ts, so declare the schema there and import it into route.ts:

    src/api/schema.ts
    import { z } from "zod";
    import type { MethodSchema } from "burger-api";

    export const GET = {
      query: z.object({ name: z.string().default("world") }),
    } satisfies MethodSchema;
    src/api/route.ts
    import { defineRoute } from "burger-api";
    import { GET as GetSchema } from "./schema";

    export const GET = defineRoute(GetSchema, (ctx) => {
      return Response.json({ message: `Hello, ${ctx.validated.query.name}!` });
    });

  5. Run it:

    bun run src/index.ts

    Open http://localhost:4000/api (try ?name=Burger) and http://localhost:4000/docs.

Ready to Go!​

You now have a Bun project set up with BurgerAPI installed.

Next, see the Configuration guide to learn how a BurgerAPI instance is configured.