Configuration

Serve

at app.serve() method you can configure the core server parameters

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;
  /**
   * 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({
  locale: 'pt',
  notFoundHandler: (req) => {
    return new Response(null, { status: 204 });
  }
});

Suggestions

We strongly discourage replacing the default error handler response format. By default, CrumbJS returns a unified ExceptionType for every error.

That consistent shape is what lets a lot of Crumb’s automation flow end-to-end:

from route definitions → to OpenAPI docs → to typed clients → to predictable frontend handling.

If you swap the error handler response structure, you’re stepping off that paved road. You’ll likely need to re-define how errors are shaped and documented across routes, and you may break assumptions in generated clients and tooling.

If you still must customize, document everything: Explicitly register non-standard 4xx/5xx responses per route; don’t rely on defaults.

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
OPENAPI=true
OPENAPI_TITLE=API
OPENAPI_DESCRIPTION=API Documentation
OPENAPI_PATH=/reference
OPENAPI_UI=scalar