Extending Rspack Configuration

The Archibald build system provides a powerful mechanism to hook into and extend the default Rspack configuration. This is achieved through a custom extension file, typically named rspack.extend.config.ts or rspack.extend.config.js.

info

For a hands-on guide with a complete example, see Adapting Rspack config.

---

1. Activation

To enable the extension, you must specify the path to your extension file in the archibald.json (or ncc.conf.json) file under the extendConfig property. The path is relative to the root of your project.

archibald.json

{
  "extendConfig": "./rspack.extend.config.ts"
}

---

2. File Structure

The extension file should export functions for the parts of the build you want to extend. Archibald supports extending both the Client (browser) and Node (SSR) configurations.

You can use the defineExtendConfig helper from @archibald/cli (or @archibald/build) to get better type support.

rspack.extend.config.ts

import { defineExtendConfig } from '@archibald/cli/build';

export const client = defineExtendConfig(({ config, parameters }) => {
    // Modify browser config here
    return config;
});

export const node = defineExtendConfig(({ config, parameters }) => {
    // Modify SSR config here
    return config;
});

Besides client and node, the extension file may also export an optional default function with the same signature — it is used as the fallback for whichever of client / node is not exported.

---

3. Extension Functions

Each extension function (client, node, default) receives an object with two properties:

config

This is the Rspack Configuration object already populated with Archibald's base and environment-specific settings. You can mutate this object directly or return a new configuration object.

parameters

This object contains metadata about the current compilation, helping you apply changes conditionally. Key parameters include:

Parameter	Type	Description
isServer	boolean	true for the Node build, false for the Client build.
isDebug	boolean	true when running in development mode.
isServe	boolean	true when running via serve (HMR active).
isSSR	boolean	true if Server-Side Rendering is enabled.
native	boolean|string	Defined if building for a native platform (e.g., Capacitor, Expo).
cliConfig	CLIConfig	The full Archibald CLI configuration.

---

4. What to write where?

Client Configuration (client)

Use this for changes that affect the code running in the user's browser:

• Adding browser-only polyfills.
• Configuring loaders for assets used only on the frontend (e.g., specific video formats).
• Injecting frontend-specific environment variables via DefinePlugin.
• Adding Rspack plugins for bundle analysis or optimization.

Node Configuration (node)

Use this for changes that affect the Server-Side Rendering (SSR) bundle:

• Handling external dependencies that should not be bundled (e.g., database drivers or native modules).
• Adding server-specific aliases.
• Configuring loaders for assets that need different treatment on the server (e.g., ignoring CSS imports).

---

5. How to Extend

Direct Mutation

The simplest way is to mutate the config object directly.

export const client = defineExtendConfig(({ config }) => {
    config.module.rules.push({
        test: /\.mp4$/,
        type: 'asset/resource',
    });
    return config;
});

Using Merging Tools

If you prefer a more declarative approach, you can use utilities like webpack-merge.

import merge from 'webpack-merge';

export const client = defineExtendConfig(({ config }) => {
    return merge(config, {
        resolve: {
            alias: {
                'custom-lib': './libs/custom.js'
            }
        }
    });
});

Conditional Logic

You can use the parameters to apply changes only in specific scenarios, such as production builds or when a specific platform is targeted.

export const client = defineExtendConfig(({ config, parameters }) => {
    if (!parameters.isDebug) {
        // Apply production-only optimizations
    }
    return config;
});