# wujies-ui

**Repository Path**: wujies/wujies-ui

## Basic Information

- **Project Name**: wujies-ui
- **Description**: 无界（Wujies）平台前端 SDK 的独立源码仓。对标 Halo 的 @halo-dev/* 已发布产物模式： npm 包负责编译期契约，宿主 Import Map 负责运行期单实例身份。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
    <a href="https://gitee.com/wujies/wujies-ui" target="_blank" rel="noopener noreferrer">
        <img width="120" src="https://gitee.com/wujies/wujies-site/raw/main/public/brand/logo-stacked.svg" alt="Wujies logo" />
    </a>
</p>

<p align="center"><b>Wujies 插件 SDK</b>，<code>@wujies/*</code> 四件套的源码与发布仓：npm 包管编译期契约，宿主 Import Map 管运行期单实例身份。</p>
<p align="center">
<a href="#包里有什么"><img alt="Scope" src="https://img.shields.io/badge/scope-@wujies-0057FE?style=flat-square" /></a>
<a href="#包里有什么"><img alt="Packages" src="https://img.shields.io/badge/packages-4-111111?style=flat-square" /></a>
<a href="#发布"><img alt="Version" src="https://img.shields.io/badge/version-5.6.x-111111?style=flat-square" /></a>
<a href="#许可"><img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square" /></a>
<br />
<a href="https://gitee.com/wujies/wujies-ui">Gitee</a>
<a href="https://www.npmjs.com/package/@wujies/ui-shared">npm</a>
<a href="https://docs.wujies.cn/docs/wujies/5.x/platform/plugin">插件开发文档</a>
</p>

---

## 这个仓库是什么

Wujies 无界平台（[wujies.cn](https://wujies.cn)）插件前端 SDK 的**独立源码仓**，一个 pnpm workspace、
四个 `@wujies/*` 包。对标 Halo 的 `@halo-dev/*` 已发布产物模式：

- **编译期**：包发进官方 npm，插件工程按 semver 装上就能 `import`，不需要宿主仓库在场；
- **运行期**：`vue` / `element-plus` / `@wujies/*` 一律留成外部依赖，宿主用 Import Map 把它们指回
  同一份实例，插件与宿主共享一个 Vue / Element Plus，杜绝双实例。

版本跟随宿主 `major.minor`，当前是 `5.6.x`。根 `package.json` 版本 `5.6.6`，`@wujies/components`
已单独 bump 到 `5.6.7`，其余三包仍是 `5.6.6`（**以各包 `package.json` 为准**）。

## 包里有什么

| 包 | 版本 | 作用 | 被谁用 |
|---|---|---|---|
| `@wujies/ui-shared` | 5.6.6 | 运行时契约层：`getPlatformRuntime` / `request` / `getRouter` / `getModal` / `globalHeaders` / `defineRemoteApp`（应用入口声明）与清单类型 | 每个插件前端 |
| `@wujies/components` | 5.6.7 | 通用 UI 组件 kit，**事实源在本仓**（`src/components/` 20 个组件），宿主与各插件都从这里取 | 宿主前端 + 各插件前端 |
| `@wujies/api-client` | 5.6.6 | 薄平台公共 API 客户端（字典 / 用户 / OSS / 配置），只调 `ui-shared` 的 `request` | 每个插件前端 |
| `@wujies/ui-plugin-bundler-kit` | 5.6.6 | 远程应用构建套件：`defineRemoteApp` 的 Vite 封装、externals、自动导入、宿主组件解析 | 各插件前端（devDependency） |

各包入口都走 `dist/`：`main` / `module` = `./dist/index.js`，`types` = `./dist/index.d.ts`。
`@wujies/components` 额外暴露 `./names`（构建期用的名字清单）与 `./style.css`（整包样式）。

## 快速开始

在本仓用 pnpm 装依赖、按拓扑构建、跑类型检查：

```bash
cd wujies-ui
pnpm install            # packageManager: pnpm@10.32.1，Node >= 20
pnpm build:sdk          # 只构建 packages/*，按依赖拓扑：ui-shared → components / api-client → bundler-kit
pnpm typecheck          # pnpm -r run typecheck
```

消费方（各插件前端）从 npm 按 semver 装，无需本仓在场：

```bash
# 插件工程的 frontend/ 目录内
pnpm add @wujies/ui-shared @wujies/components @wujies/api-client
pnpm add -D @wujies/ui-plugin-bundler-kit
```

应用入口声明与构建配置分别用两个同名但不同签名的 `defineRemoteApp`：

```ts
// src/index.ts —— 来自 @wujies/ui-shared，声明远程应用的 manifest / views
export default defineRemoteApp({
  manifest: { code: 'hello', name: '示例', version: '1.0.0', routes: [] },
  views: { home: () => import('./views/Home.vue') },
});

// vite.config.ts —— 来自 @wujies/ui-plugin-bundler-kit，产出 external + 自动导入的 Vite 配置
export default defineRemoteApp({ appCode: 'hello', root: __dirname });
```

## 开发环境

改代码后在本仓构建，产物落 `packages/*/dist`：

```bash
pnpm build              # 全量：pnpm -r --workspace-concurrency=1 run build（串行，保证拓扑顺序）
pnpm build:sdk          # 仅 packages/*：pnpm -r --filter "./packages/*" run build
pnpm --filter @wujies/components build      # 只重建组件包（vite build && vue-tsc -p tsconfig.build.json）
pnpm --filter @wujies/components build:widget  # 前台评论件的自包含 IIFE，见「components 的两条构建」
pnpm clean              # pnpm -r run clean，删各包 dist/
```

**链接到宿主验证**：各插件前端（如 `wujies/plugins/*/frontend`）从 npm 装 `@wujies/*`（`^5.6.5`），
宿主侧的 `wujies-admin`、`wujies-market/web` 用 `@wujies/components`（`^5.6.7`）。要在不发包的前提下
拿本地改动验证，就 `pnpm build:sdk` 后在目标插件工程里 `pnpm link --global @wujies/ui-shared
@wujies/components @wujies/api-client`（本仓内 `pnpm link --global` 逐个包执行）；正式回归仍以发到 npm 的
构件为准。

## `@wujies/components` 的两条构建

组件的事实源就是 `packages/components/src/components/`，不再从宿主同步。主构建（`build`）产后台用的
ESM：`vue` / `element-plus` / `@wujies/*` 全部 external，运行期由宿主 Import Map 补同一份实例；`el-*`
在构建期就编译成显式 import（预构建产物扫不到自动导入，留成 `resolveComponent` 会在运行期解析失败）。

⚠️ `KCommentSection` 还有一条**第二条构建**：前台文章页（内容中心 Thymeleaf 直出，没有 Vue、
没有 Import Map）用的那一份是自包含 IIFE。改过这个组件必须补跑一次，否则后台更新了、
前台那片评论区还是旧的：

```bash
pnpm --filter @wujies/components build:widget
# vite build --config vite.widget.config.mts
# 产物写到本仓之外：plugins/wujies-cms-plugin/src/main/resources/themes/default/comment-widget.{js,css}
# 那份在另一个 git 仓库里，要在那边一起提交；它随插件 jar 发，不进 npm 包
```

配置在 `packages/components/vite.widget.config.mts`，`emptyOutDir: false`（同目录还有 `theme.css`、
`site.js`、`toc.js`，清一次就拆别人的家），且**故意不挂在 `build` / `prepublishOnly` 上**。
两条纪律只针对这一份产物：

- `process.env.NODE_ENV` 必须在 `define` 里替换掉 —— lib/iife 构建不自动做，浏览器里 `process`
  未定义会一句 ReferenceError，整份脚本加载即废；
- 组件里的颜色一律从 `--k-cw-*` 接进局部 `--cw-*`，不要在组件自身声明同名变量，否则主题设在外面
  那一层的配色永远追不上。

本包只收**不依赖宿主业务**（不引 `@/api`、`@/store`、`@/hooks`）的通用件；业务组件
（`ImageUpload` / `UserDetail` / `Module*Settings` / 各类 Select / `KPhoneVerify` / `FileUpload` 等）
留在宿主与各 app —— 包内只声明同名占位，插件构建时该说明符是 external，运行期由宿主 `components`
槽给出真实例；占位一旦被真正渲染（说明外部化没生效、把包打进了产物）会立刻抛错，而不是安静地渲染成空白。

## 仓库布局

| 位置 | 内容 |
|---|---|
| `package.json` | workspace 根（`private: true`，`packageManager: pnpm@10.32.1`，`build` / `build:sdk` / `publish:sdk` / `typecheck` / `clean` 脚本都在这里） |
| `pnpm-workspace.yaml` | 只有一条 `packages: ['packages/*']` |
| `pnpm-lock.yaml` | pnpm 锁文件（本仓**只用 pnpm**，见「发布」） |
| `packages/tsconfig.base.json` | 各包共享的 TS 配置基线 |
| `packages/ui-shared/` | 运行时契约，源码 `src/index.ts` + `src/types.ts`，`build` = `tsc -p tsconfig.json` |
| `packages/api-client/` | 薄 API 客户端，只依赖 `@wujies/ui-shared`（`workspace:^`），`build` = `tsc -p tsconfig.json` |
| `packages/components/` | 组件事实源：`src/components/`（20 个 .vue）、`src/widget/comment-widget.ts`、`vite.config.ts`（主构建）、`vite.widget.config.mts`（前台 IIFE） |
| `packages/ui-plugin-bundler-kit/` | Vite 构建套件，导出 `defineRemoteApp` / `SHARED_EXTERNALS`，依赖 `@wujies/components` |

各包之间用 `workspace:^` 互联，发布时由 pnpm 改写成真实 semver。

## 发布

```bash
pnpm build:sdk                       # 先出产物
pnpm typecheck                       # 类型检查过一遍
pnpm publish:sdk                     # pnpm -r --filter "./packages/*" publish --access public
```

- **必须用 pnpm publish，不能换成 npm**：包间依赖写的是 `workspace:^` 协议，只有 pnpm 会在发布时把它
  改写成真实 semver（`npm publish` 会把 `workspace:^` 原样发出去，装下来直接解析失败）。
- 发到官方 npm：各包 `publishConfig` 已写死 `"registry": "https://registry.npmjs.org/"` + `"access": "public"`；
  各包 `prepublishOnly` 会自动 `pnpm run build`，所以 `dist/` 不会漏发。
- 版本号手工 bump：改 `packages/*/package.json` 的 `version`，组件单独发就只动 `@wujies/components`
  （例如 5.6.6 → 5.6.7）。本仓**没有** changesets / release 脚本，别去 `pnpm release` —— 那条命令不存在。

## 现状与前提

- **已发布到 npm**：各插件前端与宿主都以 semver（`^5.6.5` / `^5.6.7`）从 npm 安装 `@wujies/*`，
  说明这四件套已走官方 npm 发布，可独立 `import`，不需要宿主仓库在场。
- **`repository.url` 尚未跟上新仓**：`ui-shared` / `api-client` / `ui-plugin-bundler-kit` 三个包的
  `repository.url` 仍指向旧的 `gitee.com/impressivel/wujies-plugins.git`（`frontend/packages/...`），
  只有 `components` 已改成本仓 —— 以本仓 git remote（`gitee.com/wujies/wujies-ui`）为准，包内那三个字段待清理。
- **前台评论件跨仓**：`build:widget` 的产物落在 `wujies-cms-plugin` 仓库里，改 `KCommentSection` 时
  两个仓库要一起提交，否则前台评论区停在旧版。

## 许可

各包 `package.json` 的 `license` 字段均声明为 **MIT**（`publishConfig.access: public`，随包发到 npm）。
> 注意：本仓库根**尚未放 `LICENSE` 文件**，目前许可口径只来自包元数据。

## 参考

[`@wujies/ui-shared`](https://www.npmjs.com/package/@wujies/ui-shared) ·
[`@wujies/components`](https://www.npmjs.com/package/@wujies/components) ·
[`@wujies/api-client`](https://www.npmjs.com/package/@wujies/api-client) ·
[`@wujies/ui-plugin-bundler-kit`](https://www.npmjs.com/package/@wujies/ui-plugin-bundler-kit)，
[Gitee 组织](https://gitee.com/wujies) ·
文档站[「插件开发」](https://docs.wujies.cn/docs/wujies/5.x/platform/plugin)与
[「打包应用」](https://docs.wujies.cn/docs/wujies/5.x/platform/package/build)。