Configuration

Routa reads its runtime configuration from the default export of src/routa.ts. The file is required — Routa reports ROUTA_PROJECT_REQUIRED without it — even when it sets no options.

src/routa.ts

import { createRouta } from "@routa-ts/core";

export default createRouta({
  host: "127.0.0.1",
  port: 3000,
  lifecycleHeaders: true,
  responseValidation: "always",
});

host

host?: string

The interface the server binds to. Defaults to 127.0.0.1, which accepts local connections only. Container and platform deployments generally need 0.0.0.0; set that through the HOST environment variable so local development keeps the safer default.

Overridden by: HOST.

port

port?: number

The TCP port to listen on. Defaults to 3000. When the port is unavailable the server logs api.start_failed at error level and sets a non-zero exit code.

Overridden by: PORT.

logger

logger?: RoutaLogger | false

The logger instance used for runtime lifecycle events, request logging, and ctx.logger in every handler. Defaults to createLogger(), the built-in console logger at info level.

Set false to disable logging entirely. Handlers still receive ctx.logger, implemented as a complete no-op with the same type, so handler code never needs a configuration guard.

src/routa.ts

import { createRouta } from "@routa-ts/core";
import { createLogger } from "@routa-ts/core/logger";

export default createRouta({
  logger: process.env.NODE_ENV === "test" ? false : createLogger({ level: "debug" }),
});

Because RoutaLogger is a structural type, any object implementing its members is valid, including an adapter over Pino, Winston, or a hosted logging SDK. See Core reference for the full member list.

Routa enables logging when a logger is configured. Set logger: false to disable it. The runtime emits two startup lifecycle events and two request events:

Event	Level	Data
api.started	info	host, port, routes
api.start_failed	error	error, host, port
http.request	info	method, path, status, durationMs
http.error	error	method, path, status, error, name, stack, optional issues

http.error is emitted only for responses with a status of 500 or above. When response or middleware context validation fails, issues contains only Zod code and path fields. Routa never logs the rejected response or context values.

lifecycleHeaders

lifecycleHeaders?: boolean

Whether to emit deprecation headers on routes that declare deprecation. Defaults to false. When enabled, a deprecated operation responds with:

Header	Emitted when
Deprecation: true	The route declares any deprecation
Sunset: <date>	deprecation.sunset is set
Link: <target>; rel="successor-version"	deprecation.replacement is set

Routes without deprecation are unaffected regardless of this setting.

responseValidation

responseValidation?: "development" | "always"

Controls when Routa parses handler responses and middleware reject responses through their declared Zod schemas. Defaults to "development":

Value	routa dev	routa start
"development"	Parse response data	Do not parse response data
"always"	Parse response data	Parse response data

Routa always checks the result envelope and response type, selects the declared status, and performs JSON serialization. Skipping schema parsing also skips Zod transforms, defaults, and unknown-key stripping on response data. Set "always" when production must reject response drift or your response contract relies on Zod output transformations.

src/routa.ts

import { createRouta } from "@routa-ts/core";

export default createRouta({
  responseValidation: "always",
});

This setting does not affect context passed through middleware provides. Routa always parses those values before adding them to downstream context.

Environment Variables

Environment variables are read at server start and take precedence over src/routa.ts.

Variable	Overrides	Default
HOST	host	127.0.0.1
PORT	port	3000

There is no environment override for logger, lifecycleHeaders, or responseValidation; branch on your own variables inside src/routa.ts instead.

Precedence

environment variable  >  src/routa.ts  >  Routa default

Configuration is read at boot

src/routa.ts is imported once when the server starts. routa dev restarts the process on changes under src/, so config edits take effect there, but a running routa start process never re-reads them.

Next Steps

DeploySetting host and port for a container.

Core referencecreateRouta and createLogger signatures.

API evolutionWhere lifecycleHeaders comes from.