@lazarv/react-server/config

Configuration schema and helpers. Import ReactServerConfig for typed react-server.config.mjs files and generateJsonSchema to emit the JSON Schema consumed by editors.

function defineConfig(config: ReactServerConfig): ReactServerConfig;

function forChild(config?: ReactServerConfig): ReactServerConfig;

function forRoot(config?: ReactServerConfig): ReactServerConfig;

function generateJsonSchema(): Record<string, unknown>;

Generate a JSON Schema for react-server config. Suitable for $schema in JSON config files.

function loadConfig(initialConfig: ReactServerConfig): Promise<ReactServerConfig>;

const DESCRIPTIONS: Record<string, string>;

Descriptions for all config properties (key → human description). Useful for building documentation, tooltips, or custom tooling.

interface AliasEntry {
    find: string | RegExp;
    replacement: string;
}

Resolve alias entry with find and replacement.

interface BuildConfig {
    assetsDir?: string;
    cssMinify?: boolean | "lightningcss" | "esbuild";
    cssCodeSplit?: boolean;
    assetsInlineLimit?: number | ((filePath: string) => number);
    reportCompressedSize?: boolean;
    copyPublicDir?: boolean;
    modulePreload?: boolean | Record<string, unknown>;
    chunkSizeWarningLimit?: number;
    cssTarget?: string | string[] | false;
    lib?: boolean | Record<string, unknown>;
    terserOptions?: Record<string, unknown>;
    write?: boolean;
    ssrManifest?: boolean | string;
    emitAssets?: boolean;
    watch?: Record<string, unknown> | null;
    license?: boolean | Record<string, unknown>;
    dynamicImportVarsOptions?: Record<string, unknown>;
    rollupOptions?: RollupOptions;
    rolldownOptions?: RollupOptions;
    server?: {
        config?: Record<string, unknown> | ((...args: unknown[]) => Record<string, unknown>);
    };
    client?: {
        config?: Record<string, unknown> | ((...args: unknown[]) => Record<string, unknown>);
    };
}

interface CacheConfig {
    profiles?: Record<string, unknown> | unknown[];
    providers?: Record<string, unknown> | unknown[];
}

interface CssConfig {
    transformer?: "postcss" | "lightningcss";
    modules?: Record<string, unknown> | false;
    preprocessorOptions?: Record<string, unknown>;
    preprocessorMaxWorkers?: number | true;
    postcss?: string | Record<string, unknown>;
    devSourcemap?: boolean;
    lightningcss?: Record<string, unknown>;
}

interface ExportPathDescriptor {
    path: string;
    filename?: string;
    outlet?: string;
    [key: string]: unknown;
}

Export path descriptor for static export.

interface MdxConfig {
    remarkPlugins?: unknown[];
    rehypePlugins?: unknown[];
    components?: string;
}

interface OptimizeDepsConfig {
    entries?: string | string[];
    include?: string[];
    exclude?: string[];
    force?: boolean;
    needsInterop?: string[];
    extensions?: string[];
    disabled?: boolean | "build" | "dev";
    noDiscovery?: boolean;
    holdUntilCrawlEnd?: boolean;
    rollupOptions?: Record<string, unknown>;
    rolldownOptions?: Record<string, unknown>;
    esbuildOptions?: Record<string, unknown>;
}

interface ReactServerConfig {
    root?: string;
    routes?: Record<string, string> | VirtualRouteEntry[];
    base?: string;
    entry?: string;
    public?: string | false;
    name?: string;
    adapter?: AdapterOption | null;
    plugins?: PluginOption[] | ((...args: unknown[]) => PluginOption[]);
    define?: Record<string, string>;
    envDir?: string | false;
    envPrefix?: string | string[];
    cacheDir?: string;
    external?: string[] | string;
    sourcemap?: boolean | "inline" | "hidden" | "server" | "server-inline";
    compression?: boolean;
    export?: boolean | ((paths: string[]) => string[] | ExportPathDescriptor[]) | (string | ExportPathDescriptor)[];
    prerender?: boolean | Record<string, unknown>;
    cluster?: number | boolean;
    cors?: boolean | Record<string, unknown> | null;
    vite?: Record<string, unknown> | ((config: Record<string, unknown>) => Record<string, unknown>) | null;
    customLogger?: Record<string, unknown>;
    logger?: string | Record<string, unknown>;
    globalErrorComponent?: string;
    handlers?: ((...args: unknown[]) => unknown) | unknown[] | {
        pre?: unknown[];
        post?: unknown[];
    };
    importMap?: {
        imports?: Record<string, string>;
    };
    inspect?: boolean | Record<string, unknown> | null;
    runtime?: ((...args: unknown[]) => unknown) | Record<string, unknown>;
    cookies?: Record<string, unknown>;
    scrollRestoration?: boolean | {
        behavior?: "auto" | "smooth" | "instant";
    };
    host?: string | true;
    port?: number;
    console?: boolean;
    overlay?: boolean;
    assetsInclude?: string | RegExp | (string | RegExp)[];
    logLevel?: "info" | "warn" | "error" | "silent";
    clearScreen?: boolean;
    html?: Record<string, unknown>;
    worker?: {
        plugins?: unknown[];
        rollupOptions?: Record<string, unknown>;
        rolldownOptions?: Record<string, unknown>;
    };
    server?: ServerConfig;
    resolve?: ResolveConfig;
    build?: BuildConfig;
    ssr?: SsrConfig;
    css?: CssConfig;
    optimizeDeps?: OptimizeDepsConfig;
    cache?: CacheConfig;
    serverFunctions?: ServerFunctionsConfig;
    telemetry?: TelemetryConfig;
    layout?: FileRouterConfigValue;
    page?: FileRouterConfigValue;
    middleware?: FileRouterConfigValue;
    api?: FileRouterConfigValue;
    router?: FileRouterConfigValue;
    mdx?: MdxConfig;
}

Configuration for @lazarv/react-server.

This interface covers all react-server specific options as well as Vite-level pass-through configuration. Every property is optional.

Usage in JS/TS config files:

import { defineConfig } from "@lazarv/react-server/config";
export default defineConfig({
  root: "src/pages",
  adapter: "vercel",
});

Usage in JSON config files:

{
  "$schema": "node_modules/@lazarv/react-server/config/schema.json",
  "root": "src/pages"
}

interface ResolveConfig {
    alias?: Record<string, string> | AliasEntry[];
    dedupe?: string[];
    noExternal?: string[] | boolean | RegExp;
    shared?: string[];
    external?: RegExp | string | string[] | ((id: string) => boolean);
    builtins?: string[];
    conditions?: string[];
    extensions?: string[];
    mainFields?: string[];
    externalConditions?: string[];
    preserveSymlinks?: boolean;
    tsconfigPaths?: boolean;
}

interface RollupOptions {
    external?: string[] | ((id: string) => boolean) | RegExp;
    output?: Record<string, unknown>;
    plugins?: unknown[];
    input?: string | Record<string, string> | string[];
    checks?: Record<string, unknown>;
    treeshake?: boolean | Record<string, unknown>;
}

Rollup / Rolldown shared options shape.

interface ServerConfig {
    host?: string | true;
    port?: number;
    strictPort?: boolean;
    https?: boolean | Record<string, unknown>;
    cors?: boolean | Record<string, unknown>;
    open?: boolean | string;
    hmr?: boolean | Record<string, unknown>;
    ws?: false;
    allowedHosts?: string[] | true;
    fs?: {
        allow?: string[];
        deny?: string[];
        strict?: boolean;
    };
    watch?: Record<string, unknown> | null;
    origin?: string;
    proxy?: Record<string, unknown>;
    trustProxy?: boolean;
    headers?: Record<string, string>;
    warmup?: Record<string, unknown>;
    preTransformRequests?: boolean;
    sourcemapIgnoreList?: false | ((sourcePath: string, sourcemapPath: string) => boolean);
}

interface ServerFunctionDecodeLimits {
    maxRows?: number;
    maxDepth?: number;
    maxBytes?: number;
    maxBoundArgs?: number;
    maxBigIntDigits?: number;
    maxStringLength?: number;
    maxStreamChunks?: number;
}

Resource ceilings applied when decoding a client → server RSC reply (server function arguments).

These limits are enforced inside the reply decoder before any server function runs. They cap the cost of payload deserialization and protect the server from denial-of-service vectors that exploit the rich RSC reply wire format (deep nesting, huge BigInts, oversized streams, unbounded bound-argument lists, etc.).

Each limit is independent. A zero or negative value is treated as the default. Setting a value larger than the default loosens the ceiling; setting a smaller value tightens it.

When a request exceeds any limit, the decoder throws a DecodeLimitError and the request is rejected before the server function is invoked.

interface ServerFunctionsConfig {
    secret?: string;
    secretFile?: string;
    previousSecrets?: string[];
    previousSecretFiles?: string[];
    limits?: ServerFunctionDecodeLimits;
}

interface SsrConfig {
    external?: string[] | true;
    noExternal?: string | string[] | true | RegExp;
    target?: "node" | "webworker";
    resolve?: Record<string, unknown>;
    optimizeDeps?: Record<string, unknown>;
}

interface TelemetryConfig {
    enabled?: boolean;
    serviceName?: string;
    endpoint?: string;
    exporter?: "otlp" | "console" | "dev-console";
    sampleRate?: number;
    metrics?: TelemetryMetricsConfig;
}

interface TelemetryMetricsConfig {
    enabled?: boolean;
    interval?: number;
}

interface VirtualRouteEntry {
    path: string;
    file: string;
    type?: "page" | "layout" | "middleware" | "api" | "error" | "loading" | "fallback" | "default" | "template" | "state" | "metadata" | "static";
    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
    outlet?: string;
}

A virtual route entry that maps a URL path to a file outside the file-router root.

type AdapterOption = KnownAdapter | (string & {}) | ((...args: unknown[]) => unknown) | [
    string,
    Record<string, unknown>?
];

Adapter value: a known name, custom string, function, or [name, options] tuple.

type FileRouterConfigValue = Record<string, unknown> | ((...args: unknown[]) => Record<string, unknown>);

File-router configuration for layout/page/middleware/api/router. Typically { include?: string[], exclude?: string[] }.

type KnownAdapter = "aws" | "azure" | "azure-swa" | "bun" | "cloudflare" | "deno" | "docker" | "firebase" | "netlify" | "singlefile" | "vercel";

Known adapter names shipped with react-server.

type PluginOption = Record<string, unknown> | ((...args: unknown[]) => unknown) | [
    string,
    Record<string, unknown>?
] | PluginOption[] | false | null | undefined;

A Vite-style plugin: object with name, function, [name, options] tuple, nested array, false, null, or undefined.