Skip to content

Document bundler-specific UI plugin kit entry points #614

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ruibaby merged 1 commit into from
Aug 13, 2026
Merged

Document bundler-specific UI plugin kit entry points #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/developer-guide/plugin/api-changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ description: 记录每一个版本的插件 API 变更记录，方便开发者

## 2.26.0

### UI 构建工具新增独立入口

`@halo-dev/ui-plugin-bundler-kit@2.26.0` 新增 Vite 和 Rsbuild 专用入口。Vite 项目应从 `@halo-dev/ui-plugin-bundler-kit/vite` 导入 `viteConfig`，Rsbuild 项目应从 `@halo-dev/ui-plugin-bundler-kit/rsbuild` 导入 `rsbuildConfig`。包根入口中的同名导出仍可在 2.26.0 中使用，但已标记为过时，并计划在 2.27.0 中移除。迁移示例请参考 [UI 构建](./basics/ui/build.md)。

### UI 扩展支持 ESM 和异步分块

从 Halo 2.26.0 开始，插件和已激活主题的 Console / UC UI 扩展可以使用 ESM 构建和加载，并支持异步 JavaScript、CSS 和其他静态资源分块。Halo 2.x 会继续兼容已有的 IIFE 产物，无需为兼容新版本而重新构建旧插件。
Expand Down
32 changes: 17 additions & 15 deletions docs/developer-guide/plugin/basics/ui/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ Halo 插件的 UI 部分（Console / UC）以 `index.ts` 为源码入口，默
2. `rsbuildConfig`: Rsbuild 的预配置
3. `HaloUIPluginBundlerKit`：已过时，迁移方式可以参考下面的文档

从 2.26.0 开始，`viteConfig` 和 `rsbuildConfig` 分别通过构建工具专用入口导出。包根入口中的同名导出仅用于兼容已有项目，已标记为过时，并计划在 2.27.0 中移除。

### viteConfig

#### 使用
Expand All @@ -31,13 +33,13 @@ Halo 插件的 UI 部分（Console / UC）以 `index.ts` 为源码入口，默
安装依赖：

```bash
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite -D
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
```

创建 vite.config.ts:

```js
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";

export default viteConfig()
```
Expand All @@ -57,7 +59,7 @@ export default viteConfig()
#### 配置

```js
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";

export default viteConfig({
vite: {
Expand All @@ -75,7 +77,7 @@ export default viteConfig({
1. 添加路径别名

```js
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";
import path from "path";

export default viteConfig({
Expand All @@ -93,7 +95,7 @@ export default viteConfig({
2. 添加额外的 Vite 插件

```js
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";
import { defineConfig } from "vite";
import UnoCSS from "unocss/vite";

Expand All @@ -117,13 +119,13 @@ Rsbuild 是基于 Rspack 开发的上层构建工具，其优势在于兼容 Web
安装依赖：

```bash
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core -D
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core @rsbuild/plugin-vue -D
```

创建 rsbuild.config.ts:

```js
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";

export default rsbuildConfig()
```
Expand All @@ -143,7 +145,7 @@ export default rsbuildConfig()
#### 配置

```js
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";

export default rsbuildConfig({
rsbuild: {
Expand All @@ -161,7 +163,7 @@ export default rsbuildConfig({
1. 添加路径别名

```js
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";

export default rsbuildConfig({
rsbuild: {
Expand All @@ -178,7 +180,7 @@ export default rsbuildConfig({
2. 添加额外的 Rsbuild 插件

```js
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";
import { pluginSass } from "@rsbuild/plugin-sass";

export default rsbuildConfig({
Expand Down Expand Up @@ -307,7 +309,7 @@ ESM 入口仍需默认导出已有的 `PluginModule`，不应通过顶层副作

## HaloUIPluginBundlerKit（已过时）

旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 使用的方式，目前已经不再推荐，也不支持 ESM 或主题 UI provider。
旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 使用的方式，目前已经不再推荐，也不支持 ESM 或主题 UI provider。`HaloUIPluginBundlerKit` 计划在 2.27.0 中移除，请改用构建工具专用入口中的 `viteConfig` 或 `rsbuildConfig`。

## 构建输出

Expand Down Expand Up @@ -380,13 +382,13 @@ export default definePlugin({
1. 更新 `@halo-dev/ui-plugin-bundler-kit` 至 `2.26.0` 或更高版本

```bash
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 -D
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
```

2. 更新 `vite.config.ts` 文件

```typescript
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";

export default viteConfig({
vite: {
Expand Down Expand Up @@ -497,7 +499,7 @@ export default definePlugin({
viteConfig:

```js
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";

const OUT_DIR_PROD = "../src/main/resources/ui";
const OUT_DIR_DEV = "../build/resources/main/ui";
Expand All @@ -519,7 +521,7 @@ export default viteConfig({
rsbuildConfig:

```js
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";

const OUT_DIR_PROD = "../src/main/resources/ui";
const OUT_DIR_DEV = "../build/resources/main/ui";
Expand Down
8 changes: 4 additions & 4 deletions docs/developer-guide/theme/ui-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ export default definePlugin({
安装依赖：

```bash
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite -D
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
```

创建构建配置：

```ts title="ui-plugin/vite.config.ts"
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit"
import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite"

export default viteConfig({
provider: "theme",
Expand All @@ -71,13 +71,13 @@ export default viteConfig({
安装依赖：

```bash
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core -D
pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core @rsbuild/plugin-vue -D
```

创建构建配置：

```ts title="ui-plugin/rsbuild.config.ts"
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit"
import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild"

export default rsbuildConfig({
provider: "theme",
Expand Down
Loading