Configuration

Serve

at app.serve() method you can configure the core server parameters if you want to override default notFoundHandler and errorHandler here is the place

export type APIConfig = {
  /**
   * Application mode: 'development', 'production', 'test', 'staging'
   * @env inferance: 'NODE_ENV' or 'APP_MODE' (if both detected app will use 'APP_MODE')
   */
  mode: AppMode;
  /**
   * Openapi application version & version tag for your app
   * @env inferance: 'APP_VERSION'
   * @default '1.0.0'
   */
  version: string;
  /**
   * Http Port
   * @env inferance: 'PORT'
   * @default 8080
   */
  port: number;
  /**
   * Enable or disable openapi
   * @env inferance: 'OPENAPI'
   * @default true
   */
  withOpenapi: boolean;
  /**
   * Set locale
   * @warn v 0.x.x only set zod locale at boot time the internal app errors are in english
   * @env inferance: 'LOCALE'
   * @default 'en'
   */
  locale: AppLocale;
  /**
   * Openapi application title
   * @env inferance: 'OPENAPI_TITLE'
   * @default 'API'
   */
  openapiTitle: string;
  /**
   * Openapi application description
   * @env inferance: 'OPENAPI_DESCRIPTION'
   * @default 'API Documentation'
   */
  openapiDescription: string;
  /**
   * Openapi base path
   * @env inferance: 'OPENAPI_PATH'
   * @default '/reference'
   */
  openapiBasePath: string;
  /**
   * Openapi web UI
   * @env inferance: 'OPENAPI_UI'
   * @default 'scalar'
   */
  openapiUi: OpenApiUi;
  /**
   * Handler for unmatched routes (404).
   *
   * Default:
   * ```ts
   * ({ setStatus, setHeader }) => {
   *		setStatus(404);
   *		setHeader('Content-Type', 'text/plain');
   *		return '';
   * }
   * ```
   */
  notFoundHandler: NotFoundHandler;
  /**
   * Router exception handler.
   *
   * Default:
   * ```ts
   * ({ setStatus, exception }) => {
   *  setStatus(exception.status);
   *  return exception.toObject();
   * },
   * ```
   */
  errorHandler: ErrorHandler;
};

app.serve({
  notFoundHandler: (req) => {
    // req = Request
    return new Response(null, { status: 204 });
  },
  errorHandler: (ctx) => {
    // ctx = ErrorContext
    return "Upps!";
  },
});

Environment variables

Configuration can be supplied via environment variables or programmatically. The following variables are supported:

Variable	Description	Default
APP_MODE/NODE_ENV	Application mode (development, production, qa, staging)	development
APP_VERSION	API/app version	1.0.0
PORT	HTTP port	8080
OPENAPI	Enable/disable OpenAPI generation (true/false)	true
LOCALE	Zod error locale (en, es, pt)	en
OPENAPI_TITLE	Global OpenAPI title	API
OPENAPI_DESCRIPTION	Global OpenAPI description	API Documentation
OPENAPI_PATH	Base path for OpenAPI routes	/reference
OPENAPI_UI	UI for docs (swagger or scalar)	scalar

Example .env:

• bun create crumbjs creates this .env by default

APP_MODE=development
APP_VERSION=1.0.0
PORT=8080
LOCALE=en
OPENAPI=true
OPENAPI_TITLE=API
OPENAPI_DESCRIPTION=API Documentation
OPENAPI_PATH=/reference
OPENAPI_UI=scalar