Configuration

Getting your BurgerAPI server running starts with configuration. You'll import the Burger class and instantiate it, passing an options object.

For BurgerAPI CLI Users

If you used the burger-api create command, this file and the basic configuration have already been set up for you!

index.ts

import { Burger } from "burger-api";
import { globalLogger } from "./middleware/logger"; // Example: Assuming you have middleware defined

// Create a new Burger instance
const burger = new Burger({
  // --- Required ---
  apiDir: "api", // Specify the directory holding your API routes

  // --- Optional but Recommended ---
  title: "My Burger API", // Title for OpenAPI docs
  version: "1.0.0", // Version for OpenAPI docs

  // --- Other Optional Settings ---
  pageDir: "pages", // Directory for static pages
  globalMiddleware: [globalLogger], // Middleware applied to ALL requests
  apiPrefix: "api", // URL prefix for API routes (defaults to 'api')
  pagePrefix: "", // URL prefix for page routes (defaults to no prefix)
  description: "An amazing API built with BurgerAPI", // OpenAPI description
  debug: true, // Enable debug features/logging
});

// Start the server (defaults to port 4000)
burger.serve(4000);

Key Options Explained

Let's break down the essential configuration options:

• apiDir (string, Required) The heart of your API. This specifies the path (usually relative to your project root) where BurgerAPI will look for your API route files (like route.ts).

• pageDir (string, Optional) If you plan to serve static HTML pages or use .tsx for server-rendered pages, specify the directory containing these files here.

• apiRoutes (RouteDefinition[], Optional) Pre-built API route list. When set, apiDir is ignored and no API route scanning runs. Typically used by the CLI-generated production entry; you can pass it for custom builds. See the CLI build docs for production builds.

• pageRoutes (PageDefinition[], Optional) Pre-built page route list. When set, pageDir is ignored and no page scanning runs. Typically used by the CLI-generated production entry; you can pass it for custom builds.

• globalMiddleware (Middleware[], Optional) An array of middleware functions that will run for every incoming request before any route-specific logic.

• apiPrefix (string, Optional, Default: 'api') Prepends a path segment to all your API routes. With the default, a route in api/users/route.ts becomes accessible at /api/users.

• pagePrefix (string, Optional, Default: '') Similar to apiPrefix, but for page routes defined in pageDir. By default, there is no prefix.

• title, description, version (string, Optional) Crucial metadata for generating your OpenAPI documentation. It's highly recommended to set title and version.

• debug (boolean, Optional) Setting this to true will enable stack traces page for errors.

Project config file (burger.config.ts)

If you use the CLI to create a project, you get a burger.config.ts (or .js) at the project root. It defines apiDir, pageDir, apiPrefix, pagePrefix, and debug in one place. The CLI uses this file for burger-api build and burger-api build:exec so dev and production stay in sync. You can also load it in your app if you want a single source for paths and prefixes. See CLI Tool for create and build commands.

If you don't provide either apiDir/pageDir or apiRoutes/pageRoutes, the Burger class will throw: "Please provide apiDir/pageDir (for dev) or apiRoutes/pageRoutes (for production builds) when initializing the Burger class."

Starting the Server: serve()

Once configured, bring your server to life with the serve method:

burger.serve(port, callback);

• port (number, Optional, Default: 4000) Specifies the network port the server should listen on.

• callback (() => void, Optional) A function that gets called after the server has successfully started listening on the specified port. Useful for logging a confirmation message.