Archibald Configuration Deep Dive

The archibald.json file is the master configuration for the build system and the CLI. It controls everything from output paths to complex optimization strategies.

info

This page explains how archibald.json influences the build internally. For the full property reference, see Archibald CLI Configuration.

1. Project Configuration (`project`)

template: The base template to use (e.g., shop, basic).
tenants / platforms / environments: Defines the valid context for the project. The CLI uses these lists to validate commands and provide interactive choices.
rendering: Can be ssr (Server Side) or csr (Client Side).
- Impact: If ssr, the CLI builds both a server and a client bundle. If csr, it skips the server build and optimizes for a static host.
shadowing.active: Enables/disables the File Shadowing mechanism (the pre-9.1 theming block is still accepted but deprecated).
shadowing.useRustShadowing: Resolves shadowing with the Rust SWC plugin instead of the Babel loader. The deprecated spelling useRustTheming is still accepted.
output.paths: Customizes where files are saved (e.g., dist, config, swagger).

2. Optimization Settings (`cli.optimization`)

minify: Can be true/'rspack' (both use the fast native SWC minifier), or 'terser'.
- Impact: Controls which engine performs JS minification in production. true and 'rspack' are equivalent; only 'terser' opts into the slower Terser engine. CSS is always minified with Lightning CSS.
cacheGroups: Boolean (default true). Documented in depth only here — the general property reference lives in Archibald CLI Configuration.
- Impact: If true, the client build is split into a long-cached framework chunk (React ecosystem + @archibald packages), a single initial vendor chunk, and the app bundle — keeping ~90% of the initial JS cached across app-only redeploys. Async island chunks stay self-contained so enabling the split does not inflate first paint.
splitChunks: Optional custom Rspack splitChunks object.
- Impact: When set, it is passed to Rspack as-is for full manual control (independent of cacheGroups).
compression: none, brotli, gzip, or all (default all).
- Impact: Determines if pre-compressed .br/.gz assets are generated for production builds.
deduplicateCriticalCSS: Boolean.
- Impact: If true, uses css-purge during critical CSS inlining to merge duplicate rules and reduce HTML size.
preload: Boolean.
- Impact: Enables the generation of resource hint tags in the HTML <head>. (There is no separate prefetch optimization key.)

3. Development Settings (`cli.development`)

hot: Host and Port for the HMR server.
ssl.type: manual or automatic.
- Impact: If automatic, the CLI will attempt to use mkcert to generate a trusted local certificate for HTTPS development.
sourcemaps: Mode-based configuration (e.g., eval-source-map for dev).
watchOptions.ignored: Glob pattern for files that should not trigger a re-build.
detachedTypechecking: Boolean.
- Impact: If true, type checking runs in a separate process, preventing compilation stalls on large projects.

4. Integration Settings

serviceWorker.active: Triggers the Workbox generation pass during production builds.
vercel.active: If true, the build command will automatically produce a .vercel output folder ready for deployment.

Configuration Usage Flow

The following diagram illustrates how specific parameters from archibald.json flow through the CLI and influence the three Rspack configuration layers.

Parameter-Specific Impacts

Parameter	Configuration Impact
`rendering`	In Base, it determines if a server bundle is needed. In Production, it affects chunk hashing.
`minify`	In Production, it selects between `SwcJsMinimizerRspackPlugin` or `TerserPlugin`.
`splitChunks`	In Base, it defines the `framework` and `vendor` cache groups.
`compression`	In Production, it triggers the `CompressionPlugin` for Brotli or Gzip.
`watchOptions`	In Development, it controls the speed and accuracy of the file watcher.
`keepClassnames`	In Production, it ensures that class names are not mangled (required for framework DI).

1. Project Configuration (project)​

2. Optimization Settings (cli.optimization)​

3. Development Settings (cli.development)​

4. Integration Settings​

Configuration Usage Flow​

Parameter-Specific Impacts​