feat: config schema

[lazarv]

This PR adds a comprehensive configuration system for @lazarv/react-server that validates configs at dev/build time, provides full TypeScript IntelliSense for JS/TS config files via defineConfig(), and generates a JSON Schema for editor autocompletion in JSON config files.

Previously, ReactServerConfig was typed as any and invalid config options were silently ignored. Now every config property is validated with actionable error messages (including did-you-mean suggestions and inline examples), and developers get rich autocompletion regardless of their config file format.

Runtime config validation

A zero-dependency validation module that checks every config property against a declarative schema of predicate functions. Integrated into both the dev server (lib/dev/action.mjs) and production build (lib/build/action.mjs) pipelines.

Features:

• Type checking for all ~50 top-level and nested config properties
• Did-you-mean suggestions for unknown keys using Levenshtein distance
• Inline examples showing valid values for each property
• Colorful box-formatted error output via picocolors
• Context-aware messaging (dev vs. build)
• Zero false positives — precision-audited against every valid config shape

Error output example:

╭─ react-server config error ──────────────────────────────╮
│                                                          │
│  ✗ port: Expected number (0–65535), got "three-thousand" │
│    Example: port: 3000                                   │
│                                                          │
│  ✗ Unknown option "aadapter". Did you mean "adapter"?    │
│                                                          │
╰──────────────────────────────────────────────────────────╯

TypeScript type definitions

A complete ReactServerConfig interface with JSDoc descriptions and @example tags on every property. Replaces the previous ReactServerConfig = any type.

Sub-interfaces: ServerConfig, ResolveConfig, BuildConfig, SsrConfig, CssConfig, OptimizeDepsConfig, CacheConfig, ServerFunctionsConfig, MdxConfig, RollupOptions

Helper types: PluginOption, AliasEntry, KnownAdapter, AdapterOption, ExportPathDescriptor, FileRouterConfigValue

JSON Schema generator

Runtime module exporting:

• DESCRIPTIONS — human-readable descriptions for 100+ config properties (dot-notation keyed)
• generateJsonSchema() — produces a JSON Schema (draft-07) object with descriptions, type constraints, enums, and nested sub-schemas

Static JSON Schema

Pre-generated JSON Schema file. JSON config files can reference it for editor validation and autocompletion:

{ "$schema": "https://react-server.dev/schema.json" }

or locally:

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

defineConfig() typed helper

The existing defineConfig() identity function now returns the fully-typed ReactServerConfig instead of any, providing IntelliSense in JS/TS configs:

import { defineConfig } from "@lazarv/react-server/config";

export default defineConfig({
  port: 3000,        // ← autocomplete + type checking
  adapter: "vercel", // ← known adapter names suggested
});

Docs site schema endpoint (SSG)

The JSON Schema is served from https://react-server.dev/schema.json via an SSG API route, following the same pattern as sitemap.xml:

• docs/src/pages/GET.{schema.json}.server.mjs — API route handler
• Added to the export() config for static generation
• Skipped in i18n middleware

Documentation updates

Added a "Typed configuration" section to both the English and Japanese configuration pages documenting defineConfig() and $schema usage.

Design decisions

• Zero new runtime dependencies — validation uses only picocolors (already a dependency). No Zod, Ajv, or similar libraries.
• Predicate-based schema — ~150 lines of composable type checkers rather than a DSL, keeping the validation logic transparent and zero-overhead.
• Tailored error UX — did-you-mean, inline examples, and colorful box formatting provide better developer experience than generic schema validators.
• Single source of truth — schema.d.ts drives TypeScript IntelliSense, schema.mjs drives JSON Schema generation and descriptions, validate.mjs drives runtime validation. All three cover the same property set.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	react-server-docs	0356ee3	Mar 06 2026, 07:09 AM

[codecov-commenter]

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
702	1	701	7

View the top 1 failed test(s) by shortest run time

__test__/deno.spec.mjs > preset: get-started-ts

Stack Traces | 300s run time

Error: Hook timed out in 300000ms.
If this is a long-running hook, pass a timeout value as the last argument or configure it globally with "hookTimeout".
 ❯ __test__/deno.spec.mjs:46:18

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}