# `@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.

## Functions

### `defineConfig`

```ts
function defineConfig(config: ReactServerConfig): ReactServerConfig;
```

### `forChild`

```ts
function forChild(config?: ReactServerConfig): ReactServerConfig;
```

### `forRoot`

```ts
function forRoot(config?: ReactServerConfig): ReactServerConfig;
```

### `generateJsonSchema`

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

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

### `loadConfig`

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

## Constants

### `DESCRIPTIONS`

```ts
const DESCRIPTIONS: Record<string, string>;
```

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

## Interfaces

### `AliasEntry`

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

Resolve alias entry with `find` and `replacement`.

### `BuildConfig`

```ts
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>);
    };
}
```

### `CacheConfig`

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

### `CssConfig`

```ts
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>;
}
```

### `ExportPathDescriptor`

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

Export path descriptor for static export.

### `MdxConfig`

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

### `OptimizeDepsConfig`

```ts
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>;
}
```

### `ReactServerConfig`

```ts
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:**
```ts
import { defineConfig } from "@lazarv/react-server/config";
export default defineConfig({
  root: "src/pages",
  adapter: "vercel",
});
```

**Usage in JSON config files:**
```json
{
  "$schema": "node_modules/@lazarv/react-server/config/schema.json",
  "root": "src/pages"
}
```

### `ResolveConfig`

```ts
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;
}
```

### `RollupOptions`

```ts
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.

### `ServerConfig`

```ts
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);
}
```

### `ServerFunctionDecodeLimits`

```ts
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.

### `ServerFunctionsConfig`

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

### `SsrConfig`

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

### `TelemetryConfig`

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

### `TelemetryMetricsConfig`

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

### `VirtualRouteEntry`

```ts
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.

## Types

### `AdapterOption`

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

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

### `FileRouterConfigValue`

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

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

### `KnownAdapter`

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

Known adapter names shipped with react-server.

### `PluginOption`

```ts
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`.