#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

host accepts "0.0.0.0", "::", an explicit IPv4 address, an explicit IPv6 address, or a hostname. With "::", the ready log prints IPv4 local URLs plus bracketed IPv6 local/network URLs such as http://[::1]:3000; explicit IPv6 hosts are printed with brackets too.

#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: "framework-auth" },
    { name: "admin", options: { role: "admin" } },
    { name: "client-cache", options: { maxAge: 60 } },
  ],
};

The first-party auth() helper is still registered as a route-level middleware file, then routes opt into protection with RouteOptions.auth:

// src/middlewares/framework-auth.ts
import { auth, defineMiddleware } from "vextjs";

export default defineMiddleware(
  auth({
    async verify(token) {
      return token === "demo-token" ? { userId: "1" } : false;
    },
  }),
);

#VextCorsConfig

Cross-domain resource sharing configuration.

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

Access log configuration, implemented as onion-style after-middleware.

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 generation configuration.

docs.access.cacheKey is not a supported configuration field in this release. Vext rejects it to avoid implying response or access-result caching that the docs access pipeline does not currently provide.

For fixed local or deployed API targets, set servers[].url to the complete base URL including its port, for example http://127.0.0.1:3000. Use servers[].variables only for genuinely variable URL segments such as environment, region, tenant, or API version. docs.tryItOut.defaultServer controls the initial Try it out selection, while docs.tryItOut.customServer lets users temporarily enter another browser-side target without changing project config.

tagGroups is passed through as x-tagGroups only when explicitly configured. The default Vext Docs renderer builds recursive navigation from OpenAPI path segments; tagGroups is mainly for downstream OpenAPI tools that explicitly consume this vendor extension.

The default Vext Docs renderer derives Services / Utils / Models / Components / Plugins / Middlewares from code docs data. Model entries can show static schema fields, enums, options, indexes, methods, hooks, and usage. Plugins and middlewares can show inferred lifecycle/bootstrap, app extensions, middleware type, route usage, and source links. Locales, Config, Styles, and Preload are optional advanced static sources that can be enabled explicitly under docs.code; they are not shown in the default top-level documentation surface. Local loopback pages can also show Open source links for code docs entries without adding a separate configuration field.

export default {
  openapi: {
    enabled: true,
    title: "My API",
    version: "1.0.0",
    description: "My API Documentation",
    docs: {
      path: "/docs",
      renderer: "vext",
      code: {
        enabled: "auto",
      },
    },
    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 legacy fallback

Automatically map routing middleware names to OpenAPI Security Scheme for legacy middleware-only routes. New Auth examples should prefer RouteOptions.auth through a local route guard helper so runtime protection and OpenAPI security share the same source:

// Legacy only: middleware-name inference without RouteOptions.auth
app.get("/profile", { middlewares: ["auth"] }, handler);
// ↑ OpenAPI automatically infers that this route requires bearerAuth authentication

#securitySchemes

Supported security scheme types:

For apiKey schemes with in: "cookie" and for validate.cookie parameters, built-in docs can display the fields but browser Try it out cannot set the forbidden Cookie header directly. Use same-origin browser cookies or an HTTP client for manual cookie values.

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

#Adapter extension contracts

frontend.adapter is an explicit, in-process typed seam; it is not automatic plugin discovery. A VextFrontendAdapter provides name, framework, and an optional resolveBuildOptions(config). The resolver receives the resolved frontend configuration and may return synchronous or asynchronous compiler options. It does not add another bundler, nor does it enable RSC, Server Functions, or PPR.

For a delivery target other than the built-in local staging adapters, pass a VextFrontendDeployUploadAdapter object to deploy.upload.adapter. It provides name and upload(input). Its VextFrontendDeployUploadAdapterInput contains asset, sourcePath, uploadKey, and dryRun; its VextFrontendDeployUploadAdapterResult must return uploaded and may return url and etag.

export default {
  frontend: {
    deploy: {
      upload: {
        enabled: true,
        adapter: {
          name: "company-cdn",
          async upload({ asset, sourcePath, uploadKey, dryRun }) {
            if (dryRun) return { uploaded: false };
            // Upload sourcePath under uploadKey with the provider SDK of your choice.
            return {
              uploaded: true,
              url: `https://cdn.example.com/${uploadKey}`,
            };
          },
        },
      },
    },
  },
};

filesystem and mock are the only built-in upload adapter names. A provider-specific adapter stays explicit in application configuration, so the runtime does not silently install or discover cloud/bundler plugins.

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

cluster.reload only configures timing for rolling restarts triggered by vext reload / SIGHUP. Omitting cluster.reload does not disable rolling restart; Vext uses the defaults.

export default {
  cluster: {
    enabled: true,
    workers: "auto", // Detect available CPUs via availableParallelism / cgroup v1 / os.cpus
    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

Route-level response cache global configuration.

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.

#VextDevConfig

Development-only configuration. These fields are read by vext dev and ignored in production.

#VextDevOverlayConfig

export default {
  dev: {
    errorOverlay: {
      enabled: true,
      theme: "light",
      maxFrames: 10,
    },
  },
};

#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,
  },
  server: {},
  response: {
    hideInternalErrors: true,
    wrap: true,
  },
  session: {
    enabled: false,
    name: 'vext.sid',
    ttl: 86400,
    rolling: false,
    autoCommit: true,
    idLength: 32,
    cookie: {
      httpOnly: true,
      sameSite: 'lax',
      path: '/',
      secure: 'auto',
    },
  },
  csrf: {
    enabled: false,
    mode: 'auto',
    methods: ['POST', 'PUT', 'PATCH', 'DELETE'],
    headerNames: ['x-csrf-token', 'x-xsrf-token'],
    bodyField: '_csrf',
    cookie: {
      name: 'vext.csrf',
      httpOnly: false,
      sameSite: 'lax',
      path: '/',
      secure: 'auto',
    },
    fetchMetadata: true,
    origin: false,
  },
  securityHeaders: {
    enabled: false,
    preset: 'basic',
  },
  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;

#VextSessionConfig

config.session.enabled: true auto-registers Session in production, development, testing, and soft reload. The explicit session() middleware is reserved for scoped/manual registration.

VextSessionCookieOptions follows CookieSerializeOptions and adds secure: boolean | "auto". Cookie options include domain, path, expires, maxAge, httpOnly, secure, sameSite, priority, partitioned, and encode.

VextSessionStore requires get(id), set(id, data, ttlSeconds), and delete(id). Optional methods are touch(id, ttlSeconds), clearExpired(), and close(). Vext calls close() during app shutdown for configured stores and active manual Session runtimes.

For cache-backed production sessions, prefer createCacheSessionStore(cacheLike, options?) from vextjs. It accepts a structural VextCacheLike with get, set, and del, converts session TTL seconds to cache milliseconds, stores JSON strings by default, and exposes close() only when options.close is provided. config.cache.cacheHub remains route response cache configuration and does not inject a Session Store.

RouteOptions.session accepts false, true, or { enabled?, rolling?, autoCommit? }. It can disable Session for one route or enable it while the global runtime is disabled.

#VextCsrfConfig

config.csrf configures the built-in CSRF middleware. enabled: true auto-registers CSRF globally after body parsing and plugin global middleware. You can also keep it disabled and register csrf() manually for scoped paths.

Routes can opt out with route options { csrf: false }.

#VextSecurityHeadersConfig

config.securityHeaders enables Vext's built-in browser security response headers. It is disabled by default. preset: "basic" is the low-impact path for most apps; strict and custom are explicit opt-ins.

export default {
  securityHeaders: {
    enabled: true,
    preset: "basic",
    contentSecurityPolicy: {
      reportOnly: true,
      directives: {
        "default-src": ["'self'"],
        "upgrade-insecure-requests": true,
      },
    },
  },
};

basic sends X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, and X-Frame-Options: SAMEORIGIN. strict adds HTTPS-only HSTS, a minimal Permissions-Policy, COOP, and CORP, but still leaves CSP and COEP explicit. custom sends only fields you configure. Routes can opt out with { securityHeaders: false }.

#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:

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