BuntokBuntok

Buntok Configuration#

Methods on the Buntok class for environment validation, feature toggles, and production settings.

validateEnv()#

Type-safe environment variable validation using Zod. Validates process.env against a schema and exits with formatted errors if validation fails.

The buntok init command generates a src/env.ts file with a default schema. You can extend it as needed:

typescript
import { Buntok } from "@buntok/core";
import { z } from "@buntok/core/middlewares/validator";

export const env = Buntok.validateEnv({
  PORT: z.coerce.number().default(1212),
  AUTH_STORE: z.enum(["header", "cookie"]).default("header"),
  AUTH_COOKIE: z.string().default("session"),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

// env is fully typed!
console.log(env.PORT); // number (defaulted)
console.log(env.DATABASE_URL); // string (required)
Warning
If validation fails, the server prints a formatted error and calls process.exit(1). The app will not start.

Error Output#

typescript
🚨 Buntok Environment Error

Missing or invalid environment variables:
  ❯ DATABASE_URL: Expected string to be a URL
  ❯ JWT_SECRET: String must contain at least 32 character(s)

Server boot aborted.

Custom Error Handler#

Use the onError callback to handle validation errors yourself (e.g., send to Sentry, log to a file):

typescript
const env = app.validateEnv(
  {
    DATABASE_URL: z.string().url(),
    JWT_SECRET: z.string().min(32),
  },
  {
    onError: (errors) => {
      // Send to monitoring service
      console.error("Env validation failed:", errors);
      // You must exit manually when using onError
      process.exit(1);
    },
  }
);
Info
When onError is provided, the default error printing and process.exit(1) are skipped. You must handle the exit yourself.

disable() / enable()#

Toggle built-in features. Currently supports "x-powered-by" - the X-Powered-By: buntok response header.

typescript
const app = new Buntok();

// Disable X-Powered-By header (common in production)
app.disable("x-powered-by");

// Re-enable later if needed
app.enable("x-powered-by");
Info
Production defaults (performance-optimized): Request logging (logRequests) and x-request-id header generation are disabled by default in production for maximum throughput. Enable via LOG_REQUESTS=true env or app.setLogResponse(true) when you need observability.

enableReusePort()#

Enable SO_REUSEPORT for multi-process load balancing (Linux only). When enabled, multiple instances of the app can bind to the same port, and incoming requests are load-balanced at the kernel level.

typescript
const app = new Buntok();

app.enableReusePort();

// Or explicitly disable
app.enableReusePort(false);
Info
SO_REUSEPORT is Linux-only. On other platforms, a warning is logged in development mode and the option is ignored. Useful when running multiple Bun processes behind a load balancer on the same machine.

icon()#

Set a custom favicon path. Buntok serves a built-in favicon.ico by default.

typescript
app.icon("./public/favicon.svg");

Method Chaining#

typescript
const env = app.validateEnv({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

app
  .disable("x-powered-by")
  .enableReusePort()
  .icon("./public/favicon.svg")
  .cors()
  .use(compress())
  .onError(handler)
  .notFound(notFoundHandler)
  .listen(env.PORT);
PreviousRBACNext App API