Archibald CLI Configuration (archibald.json)

The archibald.json file is the central configuration for the Archibald build system and CLI. It defines how your project is structured, how the build behaves, and provides settings for development, optimization, and native platforms.

info

For how these settings influence the Rspack build internally, see the Archibald Configuration Deep Dive in the Architecture section.

---

Top-Level Properties

Property	Type	Description
$schema	string	Path to the JSON schema for validation and autocompletion in editors.
extendConfig	string	Path to an optional Rspack configuration extension file (e.g., ./rspack.extend.config.ts).
internal	object	General Archibald internal settings.
project	object	Configuration related to the project structure and source files.
cli	object	Detailed configuration for build, serve, and optimization behaviors.

---

internal

General settings for the Archibald environment.

Property	Type	Description
packageManager	string	The package manager used in the project (pnpm, npm, or yarn).
path	string	The path to the Archibald development project (primarily for framework contributors).

---

project

Defines the structure, targets, and transformations for your application.

Property	Type	Description
environments	string[]	List of target environments (e.g., local, stage, prod).
tenants	string[]	List of tenants (brands/clients) supported by the project.
platforms	string[]	List of platforms (e.g., shop, app, portal).
rendering	string	Default rendering mode: ssr (Server-Side) or csr (Client-Side).
template	string	Path to the HTML template used for generation.
shadowing	object	Configuration for file shadowing and path rewriting.
theming	object	Deprecated predecessor of shadowing.
copy	string[] | object[]	Assets or directories to be copied to the output folder after build.
source	object	Paths and file names for source code (client, server, modules).
output	object	Paths and file names for build artifacts.
docker	object	Configuration for building and pushing Docker images.
vercel	object	Settings for deploying to Vercel (e.g., runtime version).

shadowing

Configuration for Archibald's powerful file shadowing mechanism.

Property	Type	Description
active	boolean	Enables or disables the shadowing system.
useRustShadowing	boolean	Use the Rust SWC plugin for shadowing instead of the Babel loader. Also accepted as useRustTheming (deprecated).
overrideMarking	object	Require shadowing files to be explicitly marked (see below).
options	object	Low-level knobs for the shadowing resolver (see below).
config	(string | object)[]	The shadowing rules. Each rule is one path template — "src/{platform}/client(/tenant/{tenant})" — or an object with a path template plus a sibling list per placeholder, expanding one rule into several. The fixed part may use * (one directory segment) or ** (any number), and where rules overlap the most specific one wins. See the Shadowing feature guide.

theming (deprecated)

Deprecated as of 9.1

Use shadowing instead. project.theming still works and resolves identically, and will keep working until a future major removes it. Declaring it logs a one-time warning at config load.

The predecessor of shadowing, with the same properties except that config holds { test, replace } pairs rather than path templates — run pnpx @archibald/codemod . shadowing-config to move the block across.

Property	Type	Description
config	object[]	List of rewrite rules. Each rule has a test pattern (e.g., src/{platform}/client) and a replace path (e.g., src/{platform}/client/tenant/{tenant}).

options

Tuning for the resolver itself. Rarely needed — the defaults cover the standard project layout.

Property	Type	Default	Description
validExts	string[]	see VALID_LOADER_EXTENSIONS	File extensions shadowing is resolved for.
lookupExts	string[]	['ts', 'tsx', 'js', 'jsx']	Extensions probed when an import has no extension.
ignorePattern	string	(css-loader|postcss-loader)	Requests matching this pattern are left untouched.
cwd	string	process.cwd()	Directory the resolver runs in.
scriptBase	string	project.source.paths.src	Source root, appended to cwd to form the resolver root.

The active tenant and platform (and their inheritance chains) are derived from the build parameters and cannot be set here — they are shared by the Babel loader, the Rust backend, the override-marker check and the build cache key.

overrideMarking

Opt-in enforcement that every override file carries an @override marker naming the file it shadows. See the Shadowing feature guide for the full workflow, including @original/ imports.

Property	Type	Default	Description
mode	'off' | 'warn' | 'error'	off	off disables the check, warn logs violations, error fails the build.
marker	string	@override	The pragma token that marks a file as an override.
requirePath	boolean	true	When true, the marker must also name the overridden file (path relative to the source root).

---

cli

Detailed settings for the build process, development server, and optimizations.

development

Settings for the local development experience.

Property	Type	Description
open	boolean | object	Whether to open the browser automatically after build. Can specify browser (chrome, firefox, etc.) and url.
detectCircularDeps	object	Configuration for detecting circular dependencies (off, warning, error).
typeCheckTests	boolean	Enables type checking for test files during development.
automaticRuntime	boolean	Uses the new React automatic JSX runtime.
debugHydration	boolean	Enables debugging tools for React hydration issues.
fork	boolean	Runs build processes in parallel forks for improved speed.
flatEslintConfig	boolean	Informs the CLI that the project uses the new ESLint flat configuration format.
sourcemaps	boolean | string	When to generate sourcemaps (true, false, development, or production).

optimization

Controls the production build quality and performance.

Property	Type	Description
minify	boolean | string	Enables minification. Can be set to true, false, rspack, or terser.
compiler	boolean | object	Enables the experimental React Compiler for automatic memoization.
svgComponents	boolean	Transforms imported SVGs directly into React components.
compression	string	Compression type for assets: none, all, brotli, or gzip.
preact	boolean	Swaps React for Preact in production builds to reduce bundle size.
coreJS	boolean	Automatically includes core-js polyfills based on browser support targets.
splitChunks	object	Custom overrides for the Rspack/Webpack splitChunks configuration.
deduplicateCriticalCSS	boolean	Optimizes and deduplicates CSS found in the critical rendering path.
preload	boolean	Emits a <link rel="modulepreload"> hint in the document <head> for the main module (modules) entry chunk. Off by default. Per-component chunk preloading is opt-in instead via the preloaded flag on each Loadable — see Asset Orchestration › Per-component preload.

native

Configuration for mobile development using Expo or Capacitor.

Property	Type	Description
framework	string	The mobile framework to use: expo or capacitor.
useMiddleware	boolean	Enables custom development middleware for native platforms.
expo.router	boolean	Enables Expo Router for file-based routing.
capacitor.bundle	boolean	Whether to bundle the application for Capacitor.

serviceWorker

Property	Type	Description
active	boolean	Enables Service Worker generation via Workbox.
options	object	Workbox options, including swSrc (source file) and swDest (output destination).

---

Example archibald.json

{
  "internal": {
    "packageManager": "pnpm"
  },
  "project": {
    "environments": ["local", "stage", "prod"],
    "tenants": ["default"],
    "platforms": ["shop"],
    "rendering": "ssr"
  },
  "cli": {
    "development": {
      "open": true,
      "fork": true
    },
    "optimization": {
      "minify": "rspack",
      "compiler": true,
      "svgComponents": true
    }
  }
}