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

# plugins [![plugins](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)plugins](https://rsbuild.rs/config/plugins)
`plugins` is used to register Rsbuild plugins.

Rstest and Rsbuild share the same plugin system, so you can use Rsbuild plugins in Rstest.

## Using plugins

You can register Rsbuild plugins in `rstest.config.*` using the `plugins` option, see [Rsbuild - plugins](https://rsbuild.rs/config/plugins).

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [pluginReact()],
});
```

## Discover plugins

Check out the Rsbuild [plugin list](https://rsbuild.rs/plugins/list#official-plugins) to discover available plugins. These plugins can also be used with Rstest.

## Detect whether a plugin is running in Rstest \{#detect-rstest-environment}

Rsbuild plugins can run in different tools. Use [`api.context.callerName`](https://rsbuild.rs/api/javascript-api/instance#contextcallername) to detect whether the current plugin is running in Rstest before using Rstest-specific behavior.

```ts title="rstest-plugin.ts"
import type { RsbuildPlugin } from '@rsbuild/core';

export const myPlugin = (): RsbuildPlugin => ({
  name: 'my-plugin',
  setup(api) {
    if (api.context.callerName !== 'rstest') {
      return;
    }

    // Rstest-specific plugin behavior
  },
});
```

Rstest exposes its integration APIs through [`api.useExposed('rstest')`](https://rsbuild.rs/plugins/dev/core). `RstestExposeAPI` is exported from `@rstest/core` as the type of these APIs.

## Read Rstest config in Rsbuild plugins \{#get-rstest-config}


[Added in v0.11.2](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.2)

Use `getRstestConfig` to read the resolved Rstest config for the current Rsbuild environment. It combines the current project's normalized config with global and run-level options such as `pool`, `reporters`, `shard`, `update`, and `output.distPath`.

```ts title="rstest-plugin.ts"
import type { RsbuildPlugin } from '@rsbuild/core';
import type { RstestExposeAPI } from '@rstest/core';

export const myPlugin = (): RsbuildPlugin => ({
  name: 'read-rstest-config',
  setup(api) {
    const rstestConfig = api
      .useExposed<RstestExposeAPI>('rstest')
      ?.getRstestConfig();

    if (!rstestConfig) {
      return;
    }

    api.modifyRsbuildConfig((config) => ({
      ...config,
      source: {
        ...config.source,
        define: {
          ...config.source?.define,
          __RSTEST_PROJECT_NAME__: JSON.stringify(rstestConfig.name),
        },
      },
    }));
  },
});
```

In multi-project mode, `getRstestConfig` returns the effective global config merged with the config of the project that owns the current Rsbuild environment. Opaque values such as functions and provider-specific class instances retain their original identity and behavior.

**Type:** `() => Readonly<ResolvedRstestConfig>`

## Modify Rstest config in Rsbuild plugins \{#modify-rstest-config}


[Added in v0.11.1](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.1)

Use `modifyRstestConfig` to adjust the Rstest config for the current project. This API is intended for framework integrations and toolchain plugins. When a plugin already knows the current framework, Rsbuild environment, or project conventions, it can centrally add project config such as test entries, exclude rules, setup files, aliases, defines, or `testEnvironment` so users do not need to duplicate the same information in their Rstest config.

```ts title="rstest-plugin.ts"
import type { RsbuildPlugin } from '@rsbuild/core';
import type { RstestExposeAPI } from '@rstest/core';

export const myPlugin = (): RsbuildPlugin => ({
  name: 'modify-rstest-config',
  setup(api) {
    const rstestApi = api.useExposed<RstestExposeAPI>('rstest');

    rstestApi?.modifyRstestConfig((config) => {
      config.include = ['**/*.plugin.test.ts'];
    });
  },
});
```

In multi-project mode, a plugin registered in one project can only modify that project's Rstest config and does not affect other projects.

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { myPlugin } from './rstest-plugin';

export default defineConfig({
  projects: [
    {
      name: 'node',
      plugins: [myPlugin()],
    },
    {
      name: 'browser',
      plugins: [],
    },
  ],
});
```

### Type definition

```ts
import type { RstestConfig } from '@rstest/core';

export type ModifyRstestConfigCallback = (
  config: RstestConfig,
) => RstestConfig | void | Promise<RstestConfig | void>;
```

**Type:** `(callback: ModifyRstestConfigCallback) => void`

`RstestConfig` is the same user-facing config shape accepted by `defineConfig`. With `modifyRstestConfig`, you can either mutate the received `config` object directly or return a config fragment that matches the `RstestConfig` shape. Rstest merges, normalizes, and validates these changes again after the callback finishes. The callback can also be asynchronous.

Register `modifyRstestConfig` during the Rsbuild plugin `setup` phase. Do not register it from later Rsbuild config hooks such as `api.modifyRsbuildConfig`, because Rstest applies collected callbacks while resolving the Rsbuild config; callbacks registered inside those hooks are too late for the current resolution pass.

Rstest resolves file-level environment comments, such as `@rstest-environment jsdom`, before Rsbuild initializes test environments. `modifyRstestConfig` must not add or reveal files that need new environment-comment groups; use `testEnvironment` or separate `projects` before Rsbuild initialization instead.

### Modifiable config fields

`modifyRstestConfig` only adjusts the current project's config. If a callback modifies an unsupported field, Rstest throws an error that tells you to configure it in `rstest.config.*` instead.

| Config scope                                                                                                               | Supported | Notes                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `include`, `exclude`, `includeSource`                                                                                      | Yes       | Affect test discovery for the current project; Rstest recollects test entries after the callback.                |
| `setupFiles`, `globalSetup`                                                                                                | Yes       | Affect setup files for the current project; Rstest resolves them again after the callback.                       |
| `testEnvironment`                                                                                                          | Yes       | Only affects the current project's test environment.                                                             |
| `resolve`, `source`, `performance.buildCache`                                                                              | Yes       | Reapplied to Rsbuild as build config for the current project.                                                    |
| `root`, `output.module`                                                                                                    | Yes       | Re-normalized as path or output module config for the current project.                                           |
| `name`, `browser.enabled`                                                                                                  | No        | They change project identity or runtime mode and must be declared in `rstest.config.*`.                          |
| `browser.provider`, `browser.browser`, `browser.headless`, `browser.port`, `browser.strictPort`, `browser.providerOptions` | No        | They affect Browser Mode launch or dev-server selection and must be declared before Rsbuild plugins run.         |
| `projects`, `plugins`, `extends`                                                                                           | No        | They change project topology or plugin initialization order and must be declared in Rstest config or an adapter. |
| `coverage`, `reporters`, `pool`, `isolate`, `update`, `shard`, `forceRerunTriggers`                                        | No        | They are global execution strategy fields or participate in scheduling before Rsbuild plugins run.               |
| `output.distPath`                                                                                                          | No        | It changes the Rstest/Rsbuild output directory topology and must be declared in Rstest config.                   |

If you need to add Rsbuild plugins dynamically, integrate through Rstest's `extends` adapter pattern instead. An adapter can prepare the Rstest config before Rsbuild plugin initialization starts.