ExisJS

exisjs/config

The exisjs/config module exposes configuration types, Phase constants, the defineConfig() helper, and environment-loading utilities used by exis.config.ts and runtime server initializers.

Module Exports

import {  defineConfig,  mergeConfig,  loadConfig,  defaultConfig,  loadEnv,  processEnv,  resetEnv,  parseEnv,  PHASE_DEVELOPMENT_SERVER,  PHASE_PRODUCTION_BUILD,  PHASE_PRODUCTION_SERVER,  PHASE_TEST,} from 'exisjs/config'
import type {  ExisConfig,  ResolvedConfig,  CorsConfig,  LoggerConfig,  HelmetConfig,  KeepAliveConfig,  TelemetryConfig,  MetricsConfig,  HealthCheckConfig,  SwaggerConfig,  WatchConfig,  DevConfig,} from 'exisjs/config'

defineConfig(config)

A type-helper function that returns the passed ExisConfig object without modifications, providing TypeScript autocompletion and validation in IDEs.

function defineConfig(config: ExisConfig): ExisConfig

Static Configuration Example

exis.config.ts
import { defineConfig } from 'exisjs/config'
export default defineConfig({  port: 4000,  host: '0.0.0.0',  cors: {    origin: ['https://example.com', 'https://admin.example.com'],    credentials: true,    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],  },  helmet: {    enabled: true,    contentSecurityPolicy: true,    xFrameOptions: 'SAMEORIGIN',  },  logger: {    level: 'info',    pretty: false,    redact: ['req.headers.authorization', 'req.headers.cookie'],  },  cluster: {    workers: 'safe',  },  telemetry: {    enabled: true,    serviceName: 'order-service',    exporter: 'otlp',  },  healthcheck: {    enabled: true,    path: '/healthz',  },  docs: {    enabled: true,    path: '/api/docs',    title: 'Order Service API',    version: '1.0.0',  },})

Dynamic Phase-Based Configuration

You can export an asynchronous function from exis.config.ts. ExisJS passes the active phase string as the first argument, allowing you to alter settings depending on whether the application is running in development, building for production, running in production, or executing tests.

exis.config.ts
import {  defineConfig,  PHASE_DEVELOPMENT_SERVER,  PHASE_PRODUCTION_BUILD,  PHASE_PRODUCTION_SERVER,  PHASE_TEST,} from 'exisjs/config'
export default async function (phase: string, { defaultConfig }: { defaultConfig: any }) {  const isDev = phase === PHASE_DEVELOPMENT_SERVER  const isTest = phase === PHASE_TEST
  return defineConfig({    port: isTest ? 0 : Number(process.env.PORT) || 4000,    host: '0.0.0.0',
    // Spawn 1 worker in dev, safe CPU count in production    cluster: {      workers: isDev || isTest ? 1 : 'safe',    },
    // Permissive CORS in local development, strict origins in production    cors: {      origin: isDev ? '*' : ['https://app.example.com'],      credentials: true,    },
    // Human-readable logs in development, JSON structured logs in production    logger: isDev      ? { level: 'debug', pretty: true }      : isTest        ? false        : { level: 'info', pretty: false },
    // Enable API documentation in development only    docs: {      enabled: isDev,      path: '/docs',    },  })}

Phase Constants

ConstantValueTriggered When
PHASE_DEVELOPMENT_SERVER'phase-development-server'Executing npx exisjs dev
PHASE_PRODUCTION_BUILD'phase-production-build'Executing npx exisjs build
PHASE_PRODUCTION_SERVER'phase-production-server'Executing npx exisjs start
PHASE_TEST'phase-test'Executing npx exisjs test

ExisConfig Interface Reference

The root configuration schema accepted by exis.config.ts:

Network & Core Server Options

PropertyTypeDefaultDescription
portnumber4000Port for the HTTP server to listen on. Can be overridden via CLI -p.
hoststring'0.0.0.0'Network interface binding.
server'auto' | 'node' | 'bun' | 'uws''auto'HTTP server backend. Automatically selects Bun or Node when detected.
cluster{ workers?: number | 'auto' | 'safe' | 'max' }{ workers: 1 }Multi-process worker clustering. 'safe' uses available CPU cores minus 1; 'max' uses all available cores.
queue{ driver?: 'memory', maxConcurrent?, maxQueue?, timeoutMs? }not setLimits concurrent requests per process; extra requests wait, then get 503. Unknown keys or another driver stop the start.
trustProxyboolean | numberfalsetrue: trust all proxy headers (X-Forwarded-For, CF-Connecting-IP, True-Client-IP, X-Real-IP). N: trust only the N closest hops in X-Forwarded-For, counting the socket peer; CDN headers are ignored.
bodyLimitnumber10485760 (10MB)Maximum payload size in bytes for JSON and URL-encoded request bodies.
compressionbooleanfalseEnables gzip and Brotli response compression.
etagbooleanfalseWeak ETags on successful GET/HEAD responses, and 304 for a matching If-None-Match.
debugRoutingbooleanfalseLogs the matched file-system route file and applied boundaries for every request.
asyncContextbooleanfalseEnables AsyncLocalStorage context tracking (getContext()).
transformResponseboolean | ((data: any, req: any, res: any) => any)falseGlobal transformation function to wrap route responses in a standardized envelope.

Security & Middlewares

PropertyTypeDefaultDescription
corsboolean | CorsConfig{ origin: '*', methods: ['GET', 'POST', ...] }Cross-Origin Resource Sharing settings. Set to false to disable.
helmetboolean | HelmetConfig{ enabled: true }Strict security response headers (CSP, X-Frame-Options, X-Content-Type-Options).
loggerboolean | LoggerConfigfalsePino structured logger configuration with automatic credential redaction.
blockSuspiciousProbesboolean | BlockProbesOptionsfalseAutomatically drops requests targeting known exploit paths (.env, .git, wp-admin).
keepAliveboolean | KeepAliveConfigfalseHTTP keep-alive timeout and connection socket limits.

Observability & Diagnostics

PropertyTypeDefaultDescription
telemetryboolean | TelemetryConfig{ enabled: false, exporter: 'console' }OpenTelemetry tracing and span reporting ('otlp' or 'console').
metricsboolean | MetricsConfig{ enabled: false, path: '/metrics' }Prometheus text-format endpoint: request counts and duration histograms by route pattern, in-flight requests, memory and event-loop lag; aggregated across cluster workers.
healthcheckboolean | HealthCheckConfig{ enabled: false, path: '/_health' }Liveness and readiness health probe route.
docsboolean | SwaggerConfig{ enabled: false, path: '/docs' }Interactive OpenAPI / Swagger UI documentation generation.

Development & File Watching

PropertyTypeDefaultDescription
watchWatchConfig{ debounceMs: 250 }File watching paths, patterns, and debounce timings.
devDevConfig{ usePolling: true }Development server settings, including chokidar polling interval for Windows environments.
pluginsExisPlugin[][]Array of framework plugins to initialize during application bootstrap.
testTestConfig{ include: ['tests/**/*.test.ts'] }Test file matching patterns and setup file scripts.

Sub-Configuration Interfaces

CorsConfig

export interface CorsConfig {  origin?: boolean | string | RegExp | (string | RegExp)[] | CorsOriginFn  methods?: string[]  allowedHeaders?: string[]  exposedHeaders?: string[]  credentials?: boolean  maxAge?: number  preflightContinue?: boolean}

LoggerConfig

export interface LoggerConfig {  level?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'  pretty?: boolean  redact?: string[]}

HelmetConfig

export interface HelmetConfig {  enabled?: boolean  contentSecurityPolicy?: boolean  xFrameOptions?: 'DENY' | 'SAMEORIGIN'}

TelemetryConfig

export interface TelemetryConfig {  enabled: boolean  serviceName?: string  exporter?: 'otlp' | 'console'  endpoint?: string}

HealthCheckConfig

export interface HealthCheckConfig {  enabled: boolean  path?: string  checks?: (() => Promise<boolean>)[]}

SwaggerConfig

export interface SwaggerConfig {  enabled?: boolean  path?: string  specPath?: string  title?: string  version?: string  description?: string  scalar?: boolean}

WatchConfig & DevConfig

export interface WatchConfig {  paths?: string[]  ignore?: (string | RegExp)[]  extensions?: string[]  debounceMs?: number}
export interface DevConfig {  watch?: string[]  ignored?: (string | RegExp)[]  usePolling?: boolean  interval?: number  binaryInterval?: number  extensions?: string[]  debounceMs?: number  lazyRoutes?: boolean // default true: load each route file on its first request}

Environment Utility Functions

The exisjs/config module also exports low-level environment-loading helpers used internally by the CLI:

loadEnv(cwd?, mode?, override?)

Loads cascading .env files from cwd based on the specified execution mode (development, production, test).

import { loadEnv } from 'exisjs/config'
const envMap = loadEnv(process.cwd(), 'production')

parseEnv(source)

Parses raw .env string contents into a key-value record without mutating process.env.

import { parseEnv } from 'exisjs/config'
const parsed = parseEnv(`PORT=5000DATABASE_URL=postgres://user:pass@localhost:5432/db`)
Continue to Router ReferenceEdit this page on GitHub