#plugins 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.

import { defineConfig } from '@rstest/core';
import { pluginReact } from '@rsbuild/plugin-react';

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

#Discover plugins

Check out the Rsbuild plugin list to discover available plugins. These plugins can also be used with Rstest.

#Detect whether a plugin is running in Rstest

Rsbuild plugins can run in different tools. Use api.context.callerName to detect whether the current plugin is running in Rstest before using Rstest-specific behavior.

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'). RstestExposeAPI is exported from @rstest/core as the type of these APIs.

#Read Rstest config in Rsbuild plugins

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.

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

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.

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.

import { defineConfig } from '@rstest/core';
import { myPlugin } from './rstest-plugin';

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

#Type definition

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.

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.