Core Concepts
The rsx.config.json file is the single configuration file for RS-X build settings and CLI defaults in your project.
Place an rsx.config.json file in your project root to configure both the RS-X build pipeline and the interactive CLI. The file has two top-level sections: build (controls what rsx build and rsx typecheck generate) and cli (controls defaults for rsx init, rsx project, rsx add, and package manager selection).
The CLI validates the file at runtime and the VS Code extension contributes a JSON schema for it, so you get editor validation and completions while editing.
Place rsx.config.json in the project root (next to package.json). The CLI resolves it relative to the current working directory when a command runs.
If no rsx.config.json exists, all fields fall back to their built-in defaults. Most commands work without any config file at all.
The file must be valid JSON. Comments are not supported.
{
"build": {
"tsconfig": "tsconfig.app.json"
}
}Type: string | Default: none
The default tsconfig path used by rsx build and rsx typecheck when --project is not passed on the command line.
Set this to avoid repeating --project tsconfig.app.json in every build script.
Overridden by the --project flag at runtime.
Type: string | Default: none
The default output directory used by rsx build when --out-dir is not passed on the command line.
Overridden by --out-dir at runtime.
Type: boolean | Default: false
Enables generation of the preparsed AST cache module during rsx build --prod.
When true, rsx build --prod writes a preparsed module to the path in build.preparseFile. The runtime loads that module to skip parsing statically-known expressions at startup.
Has no effect in dev builds (without --prod).
See the Compiler docs for when preparse is a good fit.
Type: string | Default: src/rsx-generated/rsx-aot-preparsed.generated.ts
Path for the generated preparsed AST cache module.
Only used when build.preparse is true.
Use an app-specific path for Next.js projects (e.g. app/rsx-generated/...).
Type: boolean | Default: false
Enables generation of the compiled-expression plan cache module during rsx build --prod.
When true, rsx build --prod writes compiled plans to the path in build.compiledFile. The runtime uses compiled plans to avoid expression-tree evaluation for registered expression sites.
Per-expression behavior is still controlled by the compiled option passed directly to rsx(..., { compiled: false }) — build.compiled only gates whether production generation runs at all.
Type: string | Default: src/rsx-generated/rsx-aot-compiled.generated.ts
Path for the generated compiled-plan cache module.
Only used when build.compiled is true.
Type: string | Default: src/rsx-generated/rsx-aot-registration.generated.ts
Path for the generated registration module that loads AOT outputs (preparsed and compiled) into the runtime caches at startup.
The entry point of your app should import this file when using AOT mode.
Type: boolean | Default: false
Controls whether the compiled AOT output also embeds a resolved-dependency evaluator function alongside each compiled plan.
When false: runtime still uses compiled plans, but dependency resolution stays in shared runtime code. Smaller generated output, simpler artifacts.
When true: more dependency-resolution work is pushed into each generated compiled evaluator. Potentially faster compiled evaluation paths at the cost of larger generated output and a more aggressive AOT build.
Start with false and only enable if benchmarks show a meaningful gain for your specific expression set.
Type: "pnpm" | "npm" | "yarn" | "bun" | Default: auto-detected
Default package manager used for install, rsx init, and rsx project flows.
When not set, the CLI detects the package manager from the lockfile in the current project.
Override per-command with --pm <manager>.
Type: "latest" | "next" | Default: "latest"
Default dist-tag used when the CLI installs RS-X packages.
"latest" installs the current stable release. "next" installs the prerelease channel.
Override per-command with --next.
Type: boolean | Default: false
When true, rsx init runs a post-mutation sanity check automatically — as if --verify was always passed.
Useful in team or CI environments where you want to confirm the integration output is correct on every run.
Type: boolean | Default: true
When true, rsx project re-runs project verification after scaffolding automatically.
rsx project already verifies by default; this flag makes the behavior explicit and configurable.
Type: string | Default: "src/expressions"
The default directory suggested by rsx add when creating a new expression file.
Set to "app/expressions" for Next.js projects.
The user can change the directory during the interactive flow regardless of this default.
Type: string[] | Default: ["src", "app", "expressions"]
Preferred source roots used when rsx add ranks existing RS-X expression files for the "update existing file" flow.
Entries are plain path prefixes relative to the project root. Files under these roots are ranked above files elsewhere in the repo.
Useful in monorepos or unusual directory layouts where the default src/app/expressions ranking does not match your project structure.
All fields are optional. Only set what you need — the CLI applies built-in defaults for anything omitted.
{
"build": {
"tsconfig": "tsconfig.app.json",
"outDir": "dist",
"preparse": true,
"preparseFile": "src/rsx-generated/rsx-aot-preparsed.generated.ts",
"compiled": true,
"compiledFile": "src/rsx-generated/rsx-aot-compiled.generated.ts",
"registrationFile": "src/rsx-generated/rsx-aot-registration.generated.ts",
"compiledResolvedEvaluator": false
},
"cli": {
"packageManager": "pnpm",
"installTag": "latest",
"init": {
"verify": true
},
"project": {
"verify": true
},
"add": {
"defaultDirectory": "src/expressions",For Next.js projects, generated files typically live under app/ rather than src/. rsx project nextjs creates this config automatically.
{
"build": {
"tsconfig": "tsconfig.json",
"preparse": true,
"preparseFile": "app/rsx-generated/rsx-aot-preparsed.generated.ts",
"compiled": true,
"compiledFile": "app/rsx-generated/rsx-aot-compiled.generated.ts",
"registrationFile": "app/rsx-generated/rsx-aot-registration.generated.ts",
"compiledResolvedEvaluator": false
},
"cli": {
"packageManager": "npm",
"add": {
"defaultDirectory": "app/expressions",
"searchRoots": ["app", "src", "expressions"]
}
}
}The RS-X VS Code extension contributes a JSON schema for rsx.config.json.
Once the extension is installed, VS Code will validate the file as you type, report unknown properties, and show completion suggestions and hover descriptions for every field.
Install the extension with: rsx install vscode