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

# Solid 插件


[源码](https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-solid)

Solid 插件为 Rsbuild 提供 Solid JSX 编译、热更新和服务端渲染支持。

## 快速开始

以下配置适用于 Solid v1。使用 Solid v2 时，请参阅 [Solid v2](#solid-v2)。

### 安装插件

执行以下命令安装插件：


```sh [npm]
npm add @rsbuild/plugin-babel @rsbuild/plugin-solid -D
```

```sh [yarn]
yarn add @rsbuild/plugin-babel @rsbuild/plugin-solid -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-babel @rsbuild/plugin-solid -D
```

```sh [bun]
bun add @rsbuild/plugin-babel @rsbuild/plugin-solid -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-babel npm:@rsbuild/plugin-solid -D
```

### 注册插件

在 Rsbuild 配置中注册插件：

```ts title="rsbuild.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginSolid } from '@rsbuild/plugin-solid';

export default {
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
    }),
    pluginSolid(),
  ],
};
```

注册后，即可进行 Solid 开发。

:::tip
由于 Solid 的 JSX 依赖 Babel 进行编译，因此你需要额外添加 [Babel 插件](/zh/plugins/list/plugin-babel.md)。

Babel 编译会产生额外的编译开销，在上述例子中，我们通过 `include` 来匹配 `.jsx` 和 `.tsx` 文件，从而减少 Babel 带来的性能开销。

:::

## Solid v2

Solid v2 支持目前处于候选发布（RC）阶段，要求 `solid-js` 和 `@solidjs/web` 为 `2.0.0-rc.6` 或更高版本。默认无需安装 `@rsbuild/plugin-babel`。

安装并注册 `@rsbuild/plugin-solid` 的 RC 版本：


```sh [npm]
npm add @rsbuild/plugin-solid@rc -D
```

```sh [yarn]
yarn add @rsbuild/plugin-solid@rc -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-solid@rc -D
```

```sh [bun]
bun add @rsbuild/plugin-solid@rc -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-solid@rc -D
```

```ts title="rsbuild.config.ts"
import { pluginSolid } from '@rsbuild/plugin-solid';

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

## 解析行为

Solid 插件会将 `solid` 添加到 Rsbuild 的 [resolve.conditionNames](/zh/config/resolve/condition-names.md) 中，使 package exports 可以解析到 Solid 专属的入口。

在开发模式下，插件还会添加 `development`，用于解析 Solid 的开发环境运行时，并启用开发环境编译转换。你可以通过 [`dev: false`](#dev) 同时关闭这两项行为。

如果你配置了 `resolve.conditionNames`，插件会保留已有配置，并在前面添加这些 Solid 条件。

## 选项

如果你需要自定义 Solid 的编译行为，可以使用以下配置项。

### compiler

JSX 编译器后端。默认使用 native compiler，你可以将此选项设置为 `'babel'`，改用 `@solidjs/babel-plugin` 编译 JSX。

- **类型：** `'native' | 'babel'`
- **默认值：** `'native'`
- **版本：** `>= 2.0.0`
- **示例：**

```ts
pluginSolid({
  compiler: 'babel',
});
```

### extensions

需要作为 Solid JSX 编译的额外文件扩展名。默认的 `.jsx` 和 `.tsx` 扩展名始终保留。扩展名必须以点开头，并会添加到模块解析配置中，因此导入时可以省略扩展名。

`.mtsx` 和 `.ctsx` 文件按 TypeScript JSX 解析，其他额外扩展名按 JavaScript JSX 解析。此选项同时作用于 JSX 编译和 Solid Refresh。

- **类型：** `string[]`
- **默认值：** `[]`
- **版本：** `>= 2.0.0`
- **示例：**

```ts
pluginSolid({
  extensions: ['.mjsx', '.cjsx', '.mtsx', '.ctsx', '.solid'],
});
```

### dev

是否启用 Solid 的开发环境运行时和编译转换。设置为 `false` 可以在开发模式下同时禁用两者，设置为 `true` 可以在生产模式下同时启用两者。

如果显式配置 `solid.dev`，它会覆盖编译转换的 `dev` 设置，但不会影响运行时解析。

- **类型：** `boolean`
- **默认值：** 开发模式下为 `true`，生产模式下为 `false`
- **示例：**

```ts
pluginSolid({
  dev: false,
});
```

### refresh.disabled

是否在开发模式下禁用 Solid Refresh HMR。该选项只控制 refresh 转换，不会禁用 Rsbuild HMR。

- **类型：** `boolean`
- **默认值：** `false`
- **示例：**

```ts
pluginSolid({
  refresh: {
    disabled: true,
  },
});
```

### refresh.granular

是否生成组件级元数据，使代码变更时仅重新挂载实际发生变化的组件。

- **类型：** `boolean`
- **默认值：** `true`
- **版本：** `>= 2.0.0`
- **示例：**

```ts
pluginSolid({
  refresh: {
    granular: false,
  },
});
```

### ssr

是否生成 Solid SSR 输出。启用后，插件会为 Node.js target 设置 `generate: 'ssr'` 和 `hydratable: true`，为其他 target 设置 `generate: 'dom'` 和 `hydratable: true`。

[`solid`](#solid) 中的配置会覆盖这些默认值。

- **类型：** `boolean`
- **默认值：** `false`
- **示例：**

```ts
pluginSolid({
  ssr: true,
});
```

### solid

传递给当前 JSX 编译器的 Solid 编译选项。

- **类型：** `SolidPresetOptions`
- **默认值：** `{}`
- **示例：**

```ts
pluginSolid({
  solid: {
    generate: 'ssr',
    hydratable: true,
  },
});
```