> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack adapter reference

For setup and important caveats, see the [Rspack integration overview](/integration/rspack.md). This page contains the complete adapter API, compatibility mapping, and debugging workflow.

## API

### `withRspackConfig(options)`

Returns a configuration function that loads Rspack config and converts it to Rstest configuration.

#### `cwd`

- **Type:** `string`
- **Default:** `process.cwd()`

The working directory to resolve the Rspack config file.

When your Rspack config is in a different directory or you are running tests in a monorepo (where your `process.cwd()` is not your config directory), you can specify the `cwd` option to resolve the Rspack config file from a different directory.

```ts
export default defineConfig({
  extends: withRspackConfig({
    cwd: './packages/my-app',
  }),
});
```

#### `configPath`

- **Type:** `string`
- **Default:** `'./rspack.config.ts'`

Path to rspack config file.

#### `configName`

- **Type:** `string`
- **Default:** `undefined`

Select a named configuration when using [multi-config](https://rspack.rs/config/other-options#name) in your Rspack config file. Set to a string to use the config with a matching `name` field.

If your Rspack config exports an array of configurations:

```ts
// rspack.config.ts
export default [
  {
    name: 'client',
    target: 'web',
    entry: './src/client.ts',
    // ...
  },
  {
    name: 'server',
    target: 'node',
    entry: './src/server.ts',
    // ...
  },
];
```

You can select a specific configuration in your Rstest config:

```ts
export default defineConfig({
  extends: withRspackConfig({
    configName: 'client',
  }),
});
```

When you need to test multiple parts of your application with different configurations independently, you can define multiple Rstest projects:

```ts
export default defineConfig({
  projects: [
    {
      extends: withRspackConfig({ configName: 'server' }),
      include: ['tests/server/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRspackConfig({ configName: 'client' }),
      include: ['tests/client/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});
```

#### `env`

- **Type:** `Record<string, unknown> | string[]`
- **Default:** `undefined`

Environment values passed to the Rspack config function. This corresponds to the `env` parameter in `rspack.config.ts` when exporting a function:

```ts
// rspack.config.ts
export default (env) => {
  console.log(env); // receives the values from adapter
  return {/* ... */};
};
```

#### `nodeEnv`

- **Type:** `string`
- **Default:** `undefined`

The `NODE_ENV` value used when loading the Rspack config.

#### `modifyRspackConfig`

- **Type:** `(config: RspackOptions) => RspackOptions`
- **Default:** `undefined`

Modify the Rspack config before it gets converted to Rstest config:

```ts
export default defineConfig({
  extends: withRspackConfig({
    modifyRspackConfig: (rspackConfig) => {
      delete rspackConfig.resolve?.alias;
      return rspackConfig;
    },
  }),
});
```

## Configuration mapping

`withRspackConfig` does not copy the entire Rspack configuration into the test compiler unchanged. It routes each option according to which layer owns the behavior: equivalent concepts become Rstest configuration, compatible compiler options reach Rspack, and settings that would conflict with the generated test build remain under Rstest's control.

The following tables cover every top-level option in Rspack 2.1. Some options appear in more than one table because their sub-options have different owners. For example, Rstest must understand `resolve.alias`, while Rspack itself must receive `resolve.fallback`; similarly, Rstest derives its cache from `cache`, but does not reuse every persistent-cache tuning option.

Some Rspack options have direct equivalents in Rstest. The adapter converts these values before creating the compiler because Rstest needs them to select the test environment, resolve test modules, or prepare build output. Only the listed `resolve` fields are shared with Rsbuild; the remaining Rspack resolver options are handled in the next table.

| Rspack option                                                     | Rstest equivalent         | Notes                                                                 |
| ----------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| `name`                                                            | `name`                    | Configuration identifier                                              |
| `resolve.alias`, `extensions`, `conditionNames`, and `mainFields` | `resolve`                 | Shared module-resolution options                                      |
| `resolve.tsConfig.configFile`                                     | `source.tsconfigPath`     | TypeScript config path                                                |
| `output.module`                                                   | `output.module`           | Output module type                                                    |
| `target`                                                          | `testEnvironment`         | `'node'`/`'async-node'` maps to `'node'`, others map to `'happy-dom'` |
| `cache`                                                           | `performance.buildCache`  | Reuses storage identity, version, and build dependencies              |
| `context`                                                         | Persistent cache paths    | Resolves relative Rspack cache paths                                  |
| `mode`                                                            | Persistent cache identity | Used for the default cache name; Rstest controls the compiler mode    |

Other options still affect the final Rspack compilation but cannot safely replace the generated test configuration. The adapter combines them according to the option's semantics—for example, rules and plugins are appended, Rspack-only resolver options are merged, and the generated output path is retained. Rstest's later compiler hooks can still restore values required by the test runtime.

| Rspack option      | Behavior                                                                                                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `module`           | Merges module options and appends rules                                                                                                                                       |
| `plugins`          | Appends plugins after removing `HtmlRspackPlugin`                                                                                                                             |
| `output`           | Merges output options and preserves Rstest's path; later hooks own `iife`, `importFunctionName`, and source map filename templates                                            |
| `resolve`          | Merges Rspack-only options such as `fallback`, `byDependency`, and `tsConfig.references`; `alias: false` clears aliases, while Rstest retains required Node/CommonJS settings |
| `experiments`      | Merges experiments, while Rstest retains `runtimeMode: 'webpack'` and disables Rspack's async WebAssembly handling                                                            |
| `optimization`     | Merges optimization options, while Rstest retains its test runtime chunk and `emitOnErrors` behavior                                                                          |
| `devtool`          | Keeps inline source map variants; Rstest normalizes non-inline variants to `'nosources-source-map'`                                                                           |
| `watchOptions`     | Merges watch strategy options used when Rstest starts the compiler in watch mode                                                                                              |
| `externalsPresets` | Merges compatible presets, then keeps `node: false` so Rstest can assign the correct external type for each request                                                           |
| `cache`            | Applies memory or disabled cache settings; persistent cache is regenerated from the storage identity, version, and build dependencies described above                         |

The next group does not overlap with Rstest-owned build structure, so the adapter passes it to the compiler through Rsbuild's `mergeConfig`. This uses Rspack's standard merge semantics and keeps the generated configuration as the base. Arrays and nested objects therefore follow Rspack's normal merge behavior instead of being assigned by an adapter-specific rule.

| Rspack option           | Behavior                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `externals`             | Merges user externals with Rstest's generated externals instead of replacing them                                                           |
| `externalsType`         | Sets the default type for user externals that do not declare one; Rstest-generated externals specify their type per request                 |
| `infrastructureLogging` | Merges compiler and plugin infrastructure logging options                                                                                   |
| `loader`                | Merges custom values exposed through the loader context                                                                                     |
| `ignoreWarnings`        | Appends user warning filters to Rstest's generated filters                                                                                  |
| `resolveLoader`         | Merges loader resolution options                                                                                                            |
| `amd`                   | Applies the configured values of `require.amd` and `define.amd`                                                                             |
| `incremental`           | Applies the configured Rspack incremental build strategy; Rspack may normalize a preset such as `'safe'` into its concrete compiler options |

The remaining options either describe an application build, belong to a multi-compiler or dev-server workflow, or control output that Rstest reports itself. Applying them would replace generated test structure or create a setting with no observable effect, so the adapter leaves them under Rstest's control. `extends` is the exception: Rspack CLI consumes it while loading the config, so the adapter receives the already-merged result rather than forwarding the `extends` field.

| Rspack option     | Reason                                                                 |
| ----------------- | ---------------------------------------------------------------------- |
| `dependencies`    | Rstest selects one config instead of running a multi-compiler          |
| `extends`         | Rspack CLI resolves extended configs before conversion                 |
| `entry`           | Rstest generates entry points from test files                          |
| `output.path`     | Rstest controls the output directory                                   |
| `context`         | Rstest controls the compiler context; this still resolves cache paths  |
| `mode`            | Rstest uses development mode; this still contributes to cache identity |
| `node`            | Rstest preserves each source module's filename and directory           |
| `stats`           | Rstest controls compiler stats extraction and reporter output          |
| `bail`            | Rstest controls compilation error handling                             |
| `performance`     | Application bundle size limits do not apply to generated test bundles  |
| `watch`           | Rstest controls compiler watch mode                                    |
| `devServer`       | Rstest does not use the Rspack dev server                              |
| `lazyCompilation` | Rstest does not use Rspack lazy compilation                            |

Rspack 2.1 moved the former top-level `snapshot` option to `cache.snapshot`, so it is no longer a top-level configuration option. Persistent Rspack cache is converted into Rstest's generated build cache; Rspack-specific tuning fields such as `cache.snapshot`, `maxAge`, `portable`, and `readonly` are not copied to that generated cache.

## Debug config

Set `DEBUG=rstest` to write the resolved Rstest, Rsbuild, and Rspack configurations. The command output prints their locations. Inspect the generated Rspack configuration to verify which options reach the compiler:

```bash
DEBUG=rstest rstest
```

## Related documentation

- [Rspack configuration overview](https://rspack.rs/config)
- [Rstest configuration overview](/config/index.md)