#Configuration items

This page details all configuration fields, types, default values and usage instructions of VextJS.

#Configuration loading mechanism

VextJS uses a multi-layer configuration merging strategy, in order of priority from low to high:

DEFAULT_CONFIG (framework built-in default value)
  ↓ Deep merge
src/config/default.ts (project default configuration)
  ↓ Deep merge
src/config/{profile}.ts (config profile, such as production.ts or sg-sit.ts)
  ↓ Deep merge
src/config/local.ts (local override, optional)
  ↓ provider patch
src/config/bootstrap.ts (remote configuration during startup, optional)
  ↓ CLI override
vext start/dev --port --host ...

The merged configuration is deep-frozen through deepFreeze() and cannot be modified at runtime.

#Configuration file list

#src/config/bootstrap.ts

When the database, key or configuration center patch needs to be injected before the configuration is frozen, you can add:

import { defineBootstrapConfig } from "vextjs";

export default defineBootstrapConfig({
  providers: [
    {
      name: "remote-config",
      timeoutMs: 10_000,
      async load({ configProfile, signal, baseConfig }) {
        const response = await fetch(
          `https://config.example.com/${configProfile}.json`,
          { signal },
        );
        const remote = await response.json();
        return {
          database: remote.database,
          logger: {
            lifecycleLevel: baseConfig.logger?.lifecycleLevel ?? "concise",
          },
        };
      },
    },
  ],
});

Constraints:

• provider must return plain object patch or null
• patch only supports JSON-like structure
• When required is not declared: production defaults to fail-fast, development/test defaults to continue after warning
• In Cluster mode, the same provider patch will be reused in the same startup cycle to prevent Master / Worker from seeing different results.

#Configuration file example

// src/config/default.ts
export default {
  port: 3000,
  adapter: "native",
  cors: {
    enabled: true,
    origins: ["http://localhost:3000"],
  },
  logger: {
    level: "debug",
  },
};

// src/config/production.ts
export default {
  port: 8080,
  cors: {
    origins: ["https://api.example.com"],
  },
  logger: {
    level: "warn",
  },
  response: {
    hideInternalErrors: true,
  },
};

#Complete configuration reference

#VextConfig

#adapter

The underlying HTTP adapter supports three parameter passing methods:

// Method 1: String identification (built-in adapter)
export default {
  adapter: "native", // 'native' | 'hono' | 'fastify' | 'express' | 'koa'
};

// Method 2: Factory function (pass in custom options)
import { fastifyAdapter } from "vextjs/adapters/fastify";

export default {
  adapter: fastifyAdapter({ bodyLimit: 5 * 1024 * 1024 }),
};

//Method 3: Custom adapter instance (implementing VextAdapter interface)
export default {
  adapter: myCustomAdapter,
};

#trustProxy

When set to true:

• req.ip reads the first IP from the X-Forwarded-For request header
• req.protocol is read from the X-Forwarded-Proto request header

This option needs to be enabled when deployed behind Nginx/cloud load balancer.

#middlewares

Route-level middleware whitelist declaration. Only middleware declared here can be referenced in routes options.middlewares.

export default {
  middlewares: [
    { name: "auth" },
    { name: "admin", options: { role: "admin" } },
    { name: "client-cache", options: { maxAge: 60 } },
  ],
};

#VextCorsConfig

export default {
  cors: {
    enabled: true,
    origins: ["https://app.example.com", "https://admin.example.com"],
    credentials: true,
    maxAge: 86400,
  },
};

#VextRateLimitConfig

Global rate limit configuration, implemented based on flex-rate-limit.

export default {
  rateLimit: {
    max: 200,
    window: 120,
    //Limit flow by user ID (requires auth middleware to parse the user first)
    keyBy: (req) => req.user?.id ?? req.ip,
  },
};

#keyBy option

#VextRequestIdConfig

Request ID tracing configuration for log correlation and distributed link tracing.

#requestId vs traceId

requestId is the unique identifier of the request built into vext, and traceId usually refers to the tracing ID generated by the APM link tracking system (such as OpenTelemetry / Jaeger). Both have different usage scenarios:

Mode 1: requestId acts as traceId (simple scenario)

Change the request header name of requestId to x-trace-id to unify it with the link tracking header, which is suitable for systems that do not rely on external APM:

import { nanoid } from "nanoid";

export default {
  requestId: {
    header: "x-trace-id", // Read from x-trace-id (gateway injection)
    responseHeader: "x-trace-id", // Write back the response header
    generate: () => nanoid(), // Can be replaced by a shorter ID generator
  },
};

Mode 2: requestId + APM traceId coexist (enterprise-level scenario)

Keep requestId (log association), and transparently transmit APM's traceparent header through config.fetch.propagateHeaders, suitable for connecting to OpenTelemetry / Jaeger and other systems:

export default {
  // requestId retains the default configuration (for log correlation)
  requestId: {
    header: "x-request-id",
    responseHeader: "x-request-id",
  },
  // APM tracking headers are automatically transparently transmitted to downstream services through propagateHeaders
  fetch: {
    propagateHeaders: ["traceparent", "tracestate"],
  },
};

app.setRequestIdGenerator(() => myCustomId());

export default {
  fetch: {
    timeout: 10_000,
    retry: 1,
    retryDelay: 500,
    propagateHeaders: ["traceparent", "x-tenant-id"],
    proxy: [
      {
        name: "userService",
        baseURL: "http://user-service:3001/api",
        forwardHeaders: ["x-tenant-id"],
        headers: { "x-source": "gateway" },
        timeout: 5000,
        retry: 1,
      },
    ],
  },
};

export default {
  logger: {
    level: "debug",
    pretty: true, // Development environment beautification output
    // prettySingleLine: true, // Default value, extra fields are compressed to the same line of the message
    // prettySingleLine: false, // Restore multi-line expansion format
    // prettyIgnore: 'pid,hostname,requestId', //Default value, hide requestId
    // prettyIgnore: 'pid,hostname', // To display requestId in pretty mode
    // redactKeys: ['password', 'token'],
    // redactPaths: ['user.email', 'headers.authorization'],
    // redactValue: '[Redacted]',
  },
};

fatal > error > warn > info > debug > trace

export default {
  shutdown: {
    timeout: 30, // Container environment recommends 30 seconds
  },
};

export default {
  server: {
    requestTimeout: 120_000,
    headersTimeout: 60_000,
    keepAliveTimeout: 5_000,
    socketTimeout: 0,
    maxHeaderSize: 16 * 1024,
    maxRequestsPerSocket: 0,
    connectionsCheckingInterval: 30_000,
  },
};

{
  "code": 0,
  "data": { "id": 1, "name": "Alice" },
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": 10001,
  "message": "User does not exist",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

//hideInternalErrors: true
{ "code": 500, "message": "Internal Server Error" }

// hideInternalErrors: false (for development environment only)
{ "code": 500, "message": "Internal Server Error", "stack": "..." }

export default {
  bodyParser: {
    maxBodySize: "5mb", // Supports 'kb', 'mb', 'gb' units
  },
};

export default {
  multipart: {
    enabled: true, // Enable built-in parsing
    maxFileSize: 10 * 1024 * 1024, // 10MB
    maxFiles: 5,
    allowedMimeTypes: [
      "image/jpeg",
      "image/png",
      "image/gif",
      "application/pdf",
    ],
  },
};

#VextAccessLogConfig

export default {
  accessLog: {
    enabled: true,
    level: "info",
    skipPaths: ["/health", "/readiness", "/metrics"],
    skipPathPrefixes: ["/internal"],
    slowThreshold: 1000,
    warnOn4xx: false,
    logResponseSize: false,
  },
};

Access log output example:

POST /api/users 201 12ms | 192.168.1.1

Message fields include HTTP method, path, status code, response time (ms) and client IP; requestId is automatically injected into the JSON record field by logger's AsyncLocalStorage mixin.

#VextOpenAPIConfig

| OpenAPI documentation automatically generates configuration. | Field | Type | Default Value | Description | | ------------------------------------------------------------ | ---------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- | -------- | ---- | ------------------------------------------------------------------------------- | | enabled | boolean | dev is enabled, prod is closed | Whether to enable | | title | string | undefined | Document title | | version | string | undefined | Document version number | | description | string | undefined | Document description | | docsPath | string | '/docs' | Scalar document path | | jsonPath | string | '/openapi.json'' | OpenAPI JSON path | | jsonPublicPath |string | Same asjsonPath | Public access path of OpenAPI spec (only affects the URL referencing the spec in Scalar HTML, not routing registration). Used for reverse proxy stripping prefix scenarios, [see the guide for details](/guide/openapi#reverse proxy path prefix scenario) | |contact |object |undefined | Contact information | |license |object |undefined | License information | |servers |array |undefined | Server address list | |tags |array |undefined | Global tag definition | |guardSecurityMap |Record<string, string> |undefined | Guard → Security Scheme mapping | |securitySchemes |object |undefined | Security scheme definition | |scalar|object|{}| Scalar API Reference UI configuration (theme, dark mode, layout, favicon, etc.) | |scalar.theme |string |'default' | Theme:'default'\|'moon'\|'purple'\|'solarized'\|'bluePlanet'\|'saturn'\|'kepler'\|'mars'\|'deepSpace'\|'none' | |scalar.darkMode |boolean |false | Whether to enable dark mode | |scalar.layout |string |'modern' | Layout mode:'modern'(three columns) \|'classic'(two columns) | |scalar.favicon |string |undefined | Document page favicon URL (such as'/favicon.svg') | | scalar.sources |array |undefined | Multiple OpenAPI documentation sources ([see guide for details](/guide/openapi#import external-openapi)). Each item containstitle, urlorcontent, slug | |scalar.cdnUrl |string | jsDelivr CDN | Customize Scalar JS loading address ([see guide for details](/guide/openapi#Use custom address to override local service)). Applicable to intranet/offline/version locked | |scalar.showSidebar |boolean |true | Whether to display the sidebar | |scalar.hideModels |boolean |false | Whether to hide the Models/Schemas panel | |scalar.hiddenClients |string[] |undefined | List of hidden client languages (e.g.['php', 'ruby']) | | scalar.searchHotKey |string |'k' | Search hotkey (Ctrl+K / Cmd+K) | |scalar.proxyUrl |string |undefined | Proxy URL (Try it out request to avoid CORS) | |scalar.customCss |string |undefined | Custom CSS | | ~~tryItOutEnabled~~ | boolean |true | ~~Deprecated~~ Scalar has built-in Try it out, no separate configuration is required | | ~~docExpansion~~ | 'none' | 'list' | 'full'|'list' | ~~Deprecated~~ Please usescalar.layout` instead |

export default {
  openapi: {
    enabled: true,
    title: "My API",
    version: "1.0.0",
    description: "My API Documentation",
    scalar: {
      theme: "default",
      darkMode: false,
      layout: "modern",
      favicon: "/favicon.svg",
    },
    servers: [
      { url: "http://localhost:3000", description: "Development environment" },
      { url: "https://api.example.com", description: "Production environment" },
    ],
    tags: [
      { name: "User", description: "User management interface" },
      { name: "Order", description: "Order Management Interface" },
    ],
    securitySchemes: {
      bearerAuth: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
      },
    },
    guardSecurityMap: {
      auth: "bearerAuth",
    },
  },
};

#guardSecurityMap

Automatically map routing middleware names to OpenAPI Security Scheme:

//Use auth middleware in route declaration
app.get("/profile", { middlewares: ["auth"] }, handler);
// ↑ OpenAPI automatically infers that this route requires bearerAuth authentication

#securitySchemes

Supported security scheme types:

#VextRequestContextConfig

AsyncLocalStorage request context configuration.

export default {
  requestContext: {
    enabled: false, // Disabled to increase RPS by 3-8%
  },
};

:::warning After disabling, the following functions will be disabled:

• Logger automatically injects requestId
• app.throw() automatically parses request-level locale
• app.fetch() automatically propagates requestId :::

#VextFrontendConfig

Built-in frontend build and static serving configuration.

export default {
  frontend: {
    enabled: true,
    framework: "react",
    publicDir: "public",
    publicPath: "/",
    spaFallback: {
      scopes: [
        {
          basePath: "/admin/app",
          page: "admin/app/shell",
          exclude: ["/admin/api/**"],
        },
      ],
    },
  },
};

By default spaFallback.scopes is empty, so unknown HTML paths are not swallowed into the SPA. For mixed SSR + client-router sub-apps, declare each basePath in scopes[]. spaFallback: true is kept only as a compatibility shorthand and is not recommended for enterprise mixed projects.

#VextClusterConfig

Cluster multi-process configuration. For the complete interface definition, see src/types/app.ts VextClusterConfig.

#Basic fields

#healthCheck — heartbeat detection

#reload — Zero-downtime rolling restart

export default {
  cluster: {
    enabled: true,
    workers: "auto", // Take full advantage of all CPU cores
    autoRestart: true,
    maxRestarts: 5,
    healthCheck: {
      enabled: true,
      interval: 15000,
      timeout: 30000,
    },
    reload: {
      workerDelay: 2000,
      readyTimeout: 30000,
      shutdownTimeout: 10000,
    },
  },
};

It can also be enabled through environment variables (no need to modify the configuration file):

VEXT_CLUSTER=1 vext start

#VextCacheConfig

export default {
  cache: {
    enabled: true,
    defaultTtl: 120_000,
    maxEntries: 2000,
  },
};

Memory complete configuration:

export default {
  cache: {
    defaultTtl: 60_000,
    cacheHub: {
      mode: "memory",
      maxEntries: 1000,
      maxMemory: 50 * 1024 * 1024,
      cleanupInterval: 30_000,
      enableStats: true,
    },
  },
};

Redis configuration:

export default {
  cache: {
    defaultTtl: 2_000,
    cacheHub: {
      mode: "redis",
      url: "redis://localhost:6379",
      deleteCommand: "unlink",
      lease: {
        waitForOwner: 1_000,
        onTimeout: "fetch",
      },
      distributed: {
        channel: "vext:response-cache",
      },
    },
  },
};

MultiLevel configuration:

export default {
  cache: {
    defaultTtl: 60_000,
    cacheHub: {
      mode: "multi-level",
      memory: { maxEntries: 1000 },
      redis: { url: "redis://localhost:6379" },
      writePolicy: "both",
      backfillOnRemoteHit: true,
      remoteTimeout: 50,
      lease: true,
    },
  },
};

cacheHub only accepts response-cache-kit/cache-hub configuration and does not accept custom Store. Route-level response caching is configured via RouteOptions.cache. The public configuration unit is in milliseconds; the Cache-Control: max-age in the response header will output seconds according to the HTTP standard. See the Response Caching Guide for details.

#DEFAULT_CONFIG

The full value of the framework’s built-in default configuration:

import { DEFAULT_CONFIG } from 'vextjs';

// Complete content of DEFAULT_CONFIG:
{
  port: 3000,
  host: '0.0.0.0',
  adapter: 'native',
  trustProxy: false,
  middlewares: [],
  cors: {
    enabled: true,
    origins: ['*'],
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
    headers: ['Content-Type', 'Authorization', 'X-Request-Id'],
    credentials: false,
  },
  rateLimit: {
    enabled: true,
    max: 100,
    window: 60,
    message: 'Too Many Requests',
    keyBy: 'ip',
  },
  requestId: {
    enabled: true,
    header: 'x-request-id',
    responseHeader: 'x-request-id',
  },
  logger: {
    level: 'info',
  },
  shutdown: {
    timeout: 10,
  },
  response: {
    hideInternalErrors: true,
    wrap: true,
  },
  bodyParser: {
    enabled: true,
    maxBodySize: '1mb',
  },
  accessLog: {
    enabled: true,
    level: 'info',
    skipPaths: [],
  },
  openapi: {
    enabled: false,
  },
  requestContext: {
    enabled: true,
  },
  frontend: {
    enabled: false,
  },
}

#VextUserConfig

User-configured input type, all fields are optional. The complete VextConfig is generated by loadConfig() merging the default values.

import type { VextUserConfig } from "vextjs";

const config: VextUserConfig = {
  port: 8080,
  logger: { level: "debug" },
};

export default config;

#loadConfig

Configuration loading function, receives the configuration directory path and performs the complete configuration chain merge.

import { loadConfig } from "vextjs";
import { join } from "node:path";

const config = await loadConfig(join(process.cwd(), "src/config"), {
  rootDir: process.cwd(),
  command: "start",
  isBuilt: false,
});
// config: VextConfig (merged, frozen)

Usually there is no need to call it manually, bootstrap() will automatically call loadConfig() internally. The merge order is: DEFAULT_CONFIG < default < config profile < local < bootstrap provider patch < CLI override.

#Environment variable override

Some configurations support overriding through environment variables:

PORT=8080 VEXT_CONFIG=sg-sit vext start

#Type declaration extension

Plug-ins can add custom fields to VextConfig through declare module:

// types/vext.d.ts
declare module "vextjs" {
  interface VextConfig {
    redis?: {
      host: string;
      port: number;
      password?: string;
    };
  }
}

Later use in the configuration file will get full type hints:

// src/config/default.ts
export default {
  redis: {
    host: "localhost",
    port: 6379,
  },
};