Skip to main content

Configuration

Configure your Balda server with options and plugins.

Basic Configuration​

import { Server } from "balda";

const server = new Server({
  port: 3000,
  host: "localhost",
  controllerPatterns: ["./src/controllers/**/*.ts"],
  plugins: {
    cors: { origin: "*" },
    bodyParser: { json: { sizeLimit: "1mb" } },
  },
  swagger: true,
});

Configuration Options​

OptionTypeDefaultDescription
portnumber80Port to listen on
hoststring"0.0.0.0"Host address
controllerPatternsstring[][]Glob patterns for controller files
pluginsobjectPlugin configurations, see Plugins Overview
swaggerboolean | objecttrueEnable/configure Swagger docs
tapOptionsobjectRuntime-specific server options, see WebSockets
nodeHttpClientstring"http"Node.js HTTP module (http, https, http2, http2-secure)
httpsOptionsobject-TLS options for HTTPS/HTTP2 (Node.js only)
exposeErrorDetailsboolean | "auto"falseInclude stack/cause in built-in error bodies, see Error Handling
warning

exposeErrorDetails defaults to false. The built-in error factories are process-global, so when several Server instances coexist, the last constructed one wins.

Environment Variables​

Use environment variables for configuration:

const server = new Server({
  port: Number(process.env.PORT) || 3000,
  host: process.env.HOST || "localhost",
  plugins: {
    cors: { origin: process.env.CORS_ORIGIN || "*" },
  },
});

Common Configurations​

Development​

const server = new Server({
  port: 3000,
  host: "localhost",
  plugins: {
    cors: { origin: "*" },
    log: { logRequest: true, logResponse: true },
  },
  swagger: true,
});

Production​

const server = new Server({
  port: Number(process.env.PORT),
  host: "0.0.0.0",
  exposeErrorDetails: false,
  plugins: {
    cors: { origin: process.env.ALLOWED_ORIGINS.split(",") },
    helmet: {},
    rateLimiter: {
      keyOptions: { type: "ip", limit: 100 },
      storageOptions: { type: "memory", windowMs: 15 * 60 * 1000 },
    },
    compression: {},
  },
  swagger: false,
});

Learn More​