#Rspack adapter reference

For setup and important caveats, see the Rspack integration overview. 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.

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 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:

// 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:

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:

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:

// 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:

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.

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.

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.

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 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:

DEBUG=rstest rstest

#Related documentation

• Rspack configuration overview
• Rstest configuration overview