#Configuration items

Global middleware (such as CORS, body-parser) is automatically registered by the framework and does not need to be declared here. Only routing-level optional middleware is declared here.

The routing level can override the global configuration via options.override.rateLimit, or set it to false to disable rate limiting.

• Internal system, simple tracing → Mode 1 (rename header to x-trace-id)
• Access OpenTelemetry / Jaeger / Datadog → Mode 2 (retain requestId, configure propagateHeaders)
• For details, see [Request context → Relationship with distributed tracing](/guide/request-context#Relationship with distributed tracing traceId) :::

Generators can also be replaced dynamically via plugins:

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

#VextFetchConfig

Built-in HTTP client and request proxy configuration.

timeout must be a finite positive number no greater than 2147483647 milliseconds. retryDelay must be a finite non-negative number no greater than 2147483647 milliseconds, and function return values are validated at runtime.

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,
      },
    ],
  },
};

#VextFetchProxyTargetConfig

Proxy request header priority: target.headers < forwardHeaders < target.defaultInjectHeaders < options.headers < options.injectHeaders. Authorization does not transmit transparently by default, and both whitelist and allowAuthorizationForward: true must be configured.Agent retry priority: options.retry > target.retry > config.fetch.retry > 0. Only GET / HEAD / OPTIONS / PUT / DELETE will automatically retry when upstream 5xx or network error occurs; POST / PATCH does not retry by default, does not retry when timeout and returns local 504.

#VextLoggerConfig

| Structured log configuration, implemented based on Vext’s built-in logger kernel. | Field | Type | Default Value | Description | | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | -------- | -------------- | ------------------------------ | | level | 'fatal' \| 'error' \| 'warn' \| 'info' \| 'debug' \| 'trace' \| 'silent' | 'info' | log level | | lifecycleLevel | 'concise' \| 'verbose' | 'concise' | Framework life cycle log detail level, control system log output such as startup, loader, hot reload, cluster, etc. | | pretty | boolean | Development environment true | Whether to use the built-in pretty formatter to output readable format | | prettyIgnore | string | 'pid,hostname,requestId' | Fields to ignore in pretty mode (comma separated). Hiding requestId by default prevents mixin-injected fields from being expanded into multi-line noise, and the production environment JSON output is not affected | | prettySingleLine | boolean | true | Whether to compress extra fields in the same line of the message as JSON inline in pretty mode. Set to false to use multi-line expansion format. Only affects pretty mode, production environment JSON output is not affected | | redactKeys | string[] | [] | Desensitize structured log fields by exact key at any level. The top level level is the log protocol field and will not be overwritten | | redactPaths | string[] | [] | Desensitize structured log fields by dot notation exact path, support array numeric subscript; do not support wildcard, bracket notation, remove or function censor | | redactValue | string | '[Redacted]'' | Desensitized replacement value | | mixin |() => Record<string, unknown> |undefined | Customized log mixin function, the return value will be merged with the framework's built-in fields and injected into each log.requestIdis a framework protected field and cannot be overridden by user mixin; other fields such astrace_id/span_idare given priority by user mixin. Typical use: Inject OpenTelemetrytrace_id/span_id` to associate logs with link tracking. User mixin calls will not be executed when not configured. |

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]',
  },
};

Log level priority (from high to low):

fatal > error > warn > info > debug > trace

After setting a certain level, only logs of this level and higher will be output. Set to 'silent' to be completely silent.

The default logger also supports runtime app.logger.getLevel() / app.logger.setLevel(level) to adjust subsequent log thresholds; the configuration object itself will still be frozen after startup and should not be dynamically changed by modifying app.config.logger.level.

#VextShutdownConfig

Graceful shutdown of configuration.

After receiving the SIGTERM / SIGINT signal, the framework will:

1. Stop accepting new requests
2. Wait for the in-flight request to complete (no more than timeout seconds)
3. Execute all onClose hooks in LIFO order
4. Exit the process

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

#VextServerConfig

Inbound Node.js HTTP server layer configuration. Applicable to built-in Native / Hono / Fastify / Express / Koa adapter, also applicable to development server created by vext dev. Unset fields retain the current Node.js default value.

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

config.server only controls inbound service requests. The timeout for outbound app.fetch / app.fetch.proxy is controlled by config.fetch.timeout, the proxy target timeout, or options when calling.

#VextResponseConfig

#Export packaging

When wrap: true is enabled, res.json(data) is automatically wrapped:

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

Error response format:

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

When wrap: false is disabled, res.json(data) sends raw data directly.

#Hide internal errors

hideInternalErrors only affects the "unknown exception" 500 error path, such as the scenario where throw new Error("...") is directly used in routing, service, and middleware. It does not change the status code and response format of structured errors such as app.throw(...) or VextValidationError.

When hideInternalErrors: true is used, 500 errors are not exposed stack trace:

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

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

#VextBodyParserConfig

Request body parsing configuration.

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

After disabled, req.body is always undefined, which is suitable for pure GET service or custom body parsing scenarios.

maxBodySize supported formats:

#VextMultipartConfig

Multipart/File upload global configuration.

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",
    ],
  },
};

:::tip Fastify linkage multipart.maxFileSize only limits the size of a single file; the total request body read limit is controlled by bodyParser.maxBodySize. When using Fastify, if fastifyAdapter({ bodyLimit }) is additionally passed in, the actual read boundary will be the smaller value of the adapter bodyLimit and the overall upper limit of body-parser.