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

# Rslib adapter reference

For setup, see the [Rslib integration overview](/integration/rslib.md). This page contains the complete adapter API, configuration mapping, cache behavior, and debugging workflow.

## API

### `withRslibConfig(options)`

Returns a configuration function that loads or accepts Rslib config and converts it to Rstest configuration.

#### `cwd`

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

The `cwd` is the working directory to resolve the Rslib config file.

When your Rslib 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 Rslib config file from a different directory.

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

#### `configPath`

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

Path to rslib config file.

:::tip
If both `config` and `configPath` are provided, `config` takes precedence as the config content.
:::

#### `config`


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

- **Type:** `RslibConfig`
- **Default:** `undefined`

The inline Rslib config object to convert directly. When `config` is provided, the adapter does not call Rslib's `loadConfig`.

If `configPath` is also provided, the adapter uses it as config file metadata for [`forceRerunTriggers`](/config/test/force-rerun-triggers.md) and build cache dependency resolution, but the inline `config` still takes precedence as the config content.

```ts
import { defineConfig as defineRslibConfig } from '@rslib/core';
import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

const rslibConfig = defineRslibConfig({
  lib: [{ format: 'esm' }],
});

export default defineConfig({
  extends: withRslibConfig({
    config: rslibConfig,
  }),
});
```

#### `libId`

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

The lib config id in `lib` field to use. Set to a string to use the lib config with matching id.

By default, the adapter uses the common configuration from Rslib. If your Rslib config has multiple lib configurations:

```ts
// rslib.config.ts
export default defineConfig({
  lib: [
    {
      id: 'core',
      format: 'esm',
      dts: true,
      source: {
        define: {
          IS_CORE: true,
        },
      },
    },
    {
      id: 'utils',
      format: 'esm',
      source: {
        define: {
          IS_CORE: false,
        },
      },
    },
  ],
  // shared config
});
```

You can then reference specific lib configurations in your Rstest config. Rstest will adapt the Rslib shared configuration and the lib configuration with a matching `libId` to Rstest format.

This still does not copy the whole lib config verbatim. The adapter only takes the lib's `source`, `output`, `tools`, `plugins`, and `resolve` fields that are relevant to test execution, then merges them with the shared config before converting the result to Rstest format.

```ts
// For testing the 'core' environment
export default defineConfig({
  extends: withRslibConfig({
    libId: 'core',
  }),
  // core-specific test config
});
```

When you need to test multiple parts of your application with different configurations independently, you can define multiple Rstest projects. Each project can extend a specific lib configuration by setting the `libId` option.

```ts
export default defineConfig({
  projects: [
    {
      extends: withRslibConfig({ libId: 'node' }),
      include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRslibConfig({ libId: 'react' }),
      include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});
```

#### `modifyLibConfig`

- **Type:** `(config: RslibConfig) => RslibConfig | void`
- **Default:** `undefined`

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

```ts
export default defineConfig({
  extends: withRslibConfig({
    modifyLibConfig: (libConfig) => {
      delete libConfig.source?.define;
      return libConfig;
    },
  }),
});
```

## Cache behavior

When `performance.buildCache` is enabled in your Rslib config, `withRslibConfig()` passes it through to Rstest and Rstest will still append its own cache defaults, such as runtime digest inputs and config-file-based invalidation.

If your Rslib config does not enable `performance.buildCache`, Rstest keeps it disabled by default. Enable it explicitly in your Rstest config when you want persistent cache for test builds:

```ts
import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

export default defineConfig({
  extends: withRslibConfig(),
  performance: {
    buildCache: true,
  },
});
```

## Configuration mapping

The adapter automatically maps these Rslib options to Rstest:

Only the fields listed below are inherited. Rslib options that are not listed are ignored by default, which means test-irrelevant sections such as `dev`, `server`, and `html` are automatically pruned during conversion.

| Rslib option                 | Rstest equivalent        | Notes                                                  |
| ---------------------------- | ------------------------ | ------------------------------------------------------ |
| `root`                       | `root`                   | Project root directory                                 |
| `lib.id` selected by `libId` | `name`                   | Selected library identifier                            |
| `plugins`                    | `plugins`                | Plugin configuration                                   |
| `source.decorators`          | `source.decorators`      | Decorator support                                      |
| `source.assetsInclude`       | `source.assetsInclude`   | Additional static asset patterns                       |
| `source.define`              | `source.define`          | Global constants                                       |
| `source.include`             | `source.include`         | Source inclusion patterns                              |
| `source.exclude`             | `source.exclude`         | Source exclusion patterns                              |
| `source.transformImport`     | `source.transformImport` | On-demand import transform rules                       |
| `source.tsconfigPath`        | `source.tsconfigPath`    | TypeScript config path                                 |
| `resolve`                    | `resolve`                | Module resolution                                      |
| `output.cssModules`          | `output.cssModules`      | CSS modules configuration                              |
| `output.module`              | `output.module`          | Uses `output.module`, or falls back to `lib.format`    |
| `tools.rspack`               | `tools.rspack`           | Rspack configuration                                   |
| `tools.swc`                  | `tools.swc`              | SWC configuration                                      |
| `tools.bundlerChain`         | `tools.bundlerChain`     | Bundler chain configuration                            |
| `output.target`              | `testEnvironment`        | 'happy-dom' for web, 'node' for node and other targets |

## Debug config

To see the resolved configuration returned by the adapter, wrap it and log the result:

```typescript
export default defineConfig({
  extends: async (user) => {
    const config = await withRslibConfig({ libId: 'react' })(user);
    console.log('Extended config:', JSON.stringify(config, null, 2));
    return config;
  },
});
```

## Related documentation

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