uifork

UIFork

UIFork 是一个 CLI 工具和 React 组件库，用于管理 UI 组件版本。创建组件的多个版本，让利益相关者在这些版本间切换以进行测试并收集反馈，并在准备就绪时将最佳版本设为正式版本。

适用场景

• 用户想为 React 组件创建版本，以进行 A/B 测试或收集利益相关者的反馈
• 用户提到 uifork、组件版本管理或 UI 变体
• 用户需要 uifork CLI 命令方面的帮助（init、watch、new、fork、promote 等）
• 用户想在 React 应用（Vite、Next.js 等）中设置 uifork

安装

npm install uifork

也可以使用 yarn、pnpm 或 bun。

快速设置

1. 添加 UIFork 组件

将 UIFork 组件添加到 React 应用的根组件中。通常仅在开发和预览/预发布环境中显示（不在生产环境中显示）：

Vite：

import { UIFork } from "uifork";

const showUIFork = import.meta.env.MODE !== "production";

function App() {
  return (
    <>
      <YourApp />
      {showUIFork && <UIFork />}
    </>
  );
}

Next.js（App Router）：

// components/UIForkProvider.tsx
"use client";
import { UIFork } from "uifork";

export function UIForkProvider() {
  if (process.env.NODE_ENV === "production") return null;
  return <UIFork />;
}

// app/layout.tsx
import { UIForkProvider } from "@/components/UIForkProvider";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <UIForkProvider />
      </body>
    </html>
  );
}

Next.js（Pages Router）：

// pages/_app.tsx
import { UIFork } from "uifork";

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV !== "production" && <UIFork />}
    </>
  );
}

无需单独导入 CSS——样式会自动包含。

2. 初始化组件版本管理

npx uifork src/components/Button.tsx

也可以使用显式形式：

npx uifork init src/components/Button.tsx

这将：

• 将组件转换为可进行版本管理的分叉组件
• 生成用于跟踪所有版本的 versions.ts 文件
• 可选择启动监视服务（使用任一形式时加上 -w 标志）

UIFork 会自动检测组件使用默认导出还是命名导出，并生成正确的版本管理框架。如果文件包含多个导出组件，导致无法明确判断，请指定要分叉的导出：

npx uifork init src/components/Button.tsx --export Button
npx uifork init src/components/Button.tsx --export default

3. 像平常一样使用组件

// Default export (auto-detected)
import Button from "./components/Button";

// Named export (auto-detected)
import { Button } from "./components/Button";

// Works exactly as before - active version controlled by UIFork widget
<Button onClick={handleClick}>Click me</Button>;

CLI 命令

所有命令均使用 npx uifork：

初始化组件（简写）

直接传入路径，为现有组件初始化版本管理。

npx uifork src/components/Dropdown.tsx
npx uifork src/components/Dropdown.tsx -w  # Start watching after init

也可以使用显式形式：

npx uifork init src/components/Dropdown.tsx
npx uifork init src/components/Dropdown.tsx -w  # Start watching after init
npx uifork init src/components/Dropdown.tsx --export Button  # Specify which export to fork

watch [directory]

启动监视服务（启用 UI 小组件通信）。

npx uifork watch                    # Watch current directory (port 3030)
npx uifork watch ./src              # Watch specific directory
npx uifork watch --port 3002        # Custom port
npx uifork watch ./src --port 3002  # Directory + custom port

使用自定义端口时，请为 UIFork 组件传入相同的端口：<UIFork port={3002} />。

**重要：**生成新的版本文件后（例如手动生成或由 AI Agent 生成），请运行 watch 命令，以重新生成对应的 versions.ts 文件。

new <component-path> [version-id]

创建新的空版本文件。

npx uifork new Button         # Auto-increment version number
npx uifork new Button v3      # Specify version explicitly

fork <component-path> <version-id> [target-version]

分叉现有版本以创建新版本。

npx uifork fork Button v1           # Fork v1 to auto-incremented version
npx uifork fork Button v1 v2        # Fork v1 to specific version
npx uifork duplicate Button v1 v2   # Alias for fork

rename <component-path> <version-id> <new-version-id>

重命名版本。

npx uifork rename Button v1 v2

delete <component-path> <version-id>

删除版本（必须至少保留一个版本）。

npx uifork delete Button v2

promote <component-path> <version-id>

将某个版本设为主组件，并移除所有版本管理框架。

npx uifork promote Button v2

这将：

• 用 Button.v2.tsx 的内容替换 Button.tsx
• 删除所有版本文件（Button.v*.tsx）
• 删除 Button.versions.ts
• 实际上“撤销”版本管理系统

文件结构

运行 npx uifork src/components/Button.tsx（或 npx uifork init src/components/Button.tsx）后：

src/components/
├── Button.tsx              # Wrapper component (import this)
├── Button.versions.ts      # Version configuration
├── Button.v1.tsx           # Original component (version 1)
├── Button.v2.tsx           # Additional versions
└── Button.v1_1.tsx         # Sub-versions (v1.1, v2.1, etc.)

默认导出和命名导出均受支持。UIFork 会在 init 期间自动检测导出方式，并在所有版本文件中保持一致。

版本命名

• v1、v2、v3——主版本
• v1_1、v1_2——子版本（在 UI 中显示为 V1.1、V1.2）
• v2_1、v2_2——v2 的子版本

UIFork 小组件功能

UIFork 组件会提供一个浮动 UI 小组件，支持：

• 切换版本——点击即可在不同版本间切换
• 创建新版本——点击“+”即可创建空白版本
• 分叉版本——分叉现有版本以继续迭代
• 重命名版本——为版本设置有意义的名称
• 删除版本——移除不再需要的版本
• 设为正式版本——将某个版本设为主组件
• 在编辑器中打开——点击即可在 VS Code/Cursor 中打开版本文件

键盘快捷键：Cmd/Ctrl + Arrow Up/Down 可循环切换版本

**设置：**主题（浅色/深色/系统）、位置、代码编辑器偏好

自定义环境门控

如需更精确地控制 UIFork 的显示时机：

// Enable via NEXT_PUBLIC_ENABLE_UIFORK=true or VITE_ENABLE_UIFORK=true
const showUIFork =
  process.env.NODE_ENV !== "production" ||
  process.env.NEXT_PUBLIC_ENABLE_UIFORK === "true";

适用于：

• 在特定预览分支中显示
• 为暂存环境中的内部相关人员启用
• 通过功能标志进行门控

常见工作流

开始为组件启用版本管理

1. 安装 uifork：npm install uifork
2. 将 <UIFork /> 组件添加到应用根节点
3. 初始化：npx uifork src/components/MyComponent.tsx（或 npx uifork init src/components/MyComponent.tsx）
4. 启动监视服务：npx uifork watch
5. 使用小组件创建版本并在版本之间切换

创建新版本

# Create empty version
npx uifork new Button

# Or fork existing version
npx uifork fork Button v1

将版本升级为生产版本

npx uifork promote Button v2

这会移除所有版本管理，并将 v2 设为主组件。

工作原理

1. ForkedComponent 从 localStorage 读取当前激活的版本，并渲染对应的组件
2. UIFork 连接到监视服务并显示所有可用版本
3. 选择一个版本会更新 localStorage，从而触发 ForkedComponent 重新渲染
4. 监视服务会监控文件系统中的新版本文件，并自动更新 versions.ts

生成新版本文件后： 手动或通过 AI Agent 创建版本文件后，运行 npx uifork watch 以重新生成 versions.ts 文件，让新版本显示在 UIFork 小组件中。