uifork

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UIFork

UIFork is a CLI tool and React component library for managing UI component versions. Create multiple versions of components, let stakeholders switch between them to test and gather feedback, and promote the best one when ready.

UIFork是一款用于管理UI组件版本的CLI工具和React组件库。你可以创建组件的多个版本，让利益相关者在不同版本间切换以进行测试和收集反馈，待确定最优版本后将其设为正式版本。

When to Use

适用场景

User wants to version React components for A/B testing or stakeholder feedback
User mentions uifork, component versioning, or UI variations
User needs help with uifork CLI commands (init, watch, new, fork, promote, etc.)
User wants to set up uifork in a React app (Vite, Next.js, etc.)

用户希望为React组件添加版本控制以进行A/B测试或收集利益相关者反馈
用户提及UIFork、组件版本控制或UI变体
用户需要UIFork CLI命令（init、watch、new、fork、promote等）的使用帮助
用户希望在React应用（Vite、Next.js等）中搭建UIFork

Installation

安装

bash

npm install uifork

Or use yarn, pnpm, or bun.

bash

npm install uifork

也可以使用yarn、pnpm或bun进行安装。

Quick Setup

快速设置

1. Add UIFork Component

1. 添加UIFork组件

Add the

UIFork

component to your React app root. Typically shown in development and preview/staging (not production):

Vite:

tsx

import { UIFork } from "uifork";

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

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

Next.js (App Router):

tsx

// 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):

tsx

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

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

No separate CSS import needed - styles are automatically included.

将

UIFork

组件添加到你的React应用根目录。通常在开发、预览或预发布环境中显示（生产环境不显示）：

Vite：

tsx

import { UIFork } from "uifork";

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

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

Next.js（App Router）：

tsx

// 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）：

tsx

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

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

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

2. Initialize Component Versioning

2. 初始化组件版本控制

bash

npx uifork init src/components/Button.tsx

This will:

Convert the component into a forked component that can be versioned
Generate a
```
versions.ts
```
file to track all versions
Optionally start the watch server (use
```
-w
```
flag)

bash

npx uifork init src/components/Button.tsx

该命令会：

将组件转换为可进行版本控制的分支组件
生成
```
versions.ts
```
文件以追踪所有版本
可选启动监听服务器（使用
```
-w
```
参数）

3. Use Component Normally

3. 正常使用组件

tsx

import Button from "./components/Button";

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

tsx

import Button from "./components/Button";

// 用法与之前完全一致——当前激活版本由UIFork小部件控制
<Button onClick={handleClick}>Click me</Button>;

CLI Commands

CLI命令

All commands use

npx uifork

所有命令均使用

npx uifork

：

init <component-path>

init <component-path>

Initialize versioning for an existing component.

bash

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

为现有组件初始化版本控制。

bash

npx uifork init src/components/Dropdown.tsx
npx uifork init src/components/Dropdown.tsx -w  # 初始化后启动监听

watch [directory]

watch [directory]

Start the watch server (enables UI widget communication).

bash

npx uifork watch              # Watch current directory
npx uifork watch ./src        # Watch specific directory

启动监听服务器（支持UI小部件通信）。

bash

npx uifork watch              # 监听当前目录
npx uifork watch ./src        # 监听指定目录

new <component-path> [version-id]

new <component-path> [version-id]

Create a new empty version file.

bash

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

创建新的空版本文件。

bash

npx uifork new Button         # 自动递增版本号
npx uifork new Button v3      # 显式指定版本

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

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

Fork an existing version to create a new one.

bash

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

基于现有版本创建新的衍生版本。

bash

npx uifork fork Button v1           # 基于v1创建自动递增的新版本
npx uifork fork Button v1 v2        # 基于v1创建指定版本v2
npx uifork duplicate Button v1 v2   # fork命令的别名

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

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

Rename a version.

bash

npx uifork rename Button v1 v2

重命名版本。

bash

npx uifork rename Button v1 v2

delete <component-path> <version-id>

delete <component-path> <version-id>

Delete a version (must have at least one version remaining).

bash

npx uifork delete Button v2

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

bash

npx uifork delete Button v2

promote <component-path> <version-id>

promote <component-path> <version-id>

Promote a version to be the main component and remove all versioning scaffolding.

bash

npx uifork promote Button v2

This will:

Replace
```
Button.tsx
```
with content from
```
Button.v2.tsx
```
Delete all version files (
```
Button.v*.tsx
```
)
Delete
```
Button.versions.ts
```
Effectively "undo" the versioning system

将指定版本升级为主要组件，并移除所有版本控制架构。

bash

npx uifork promote Button v2

该命令会：

用
```
Button.v2.tsx
```
的内容替换
```
Button.tsx
```
删除所有版本文件（
```
Button.v*.tsx
```
）
删除
```
Button.versions.ts
```
相当于“撤销”版本控制系统

File Structure

文件结构

After running

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.)

运行

npx uifork init src/components/Button.tsx

后：

src/components/
├── Button.tsx              # 包装组件（导入此文件）
├── Button.versions.ts      # 版本配置文件
├── Button.v1.tsx           # 原始组件（版本1）
├── Button.v2.tsx           # 新增版本
└── Button.v1_1.tsx         # 子版本（UI中显示为V1.1、V1.2等）

Version Naming

版本命名规则

```
v1
```
,
```
v2
```
,
```
v3
```
- Major versions
```
v1_1
```
,
```
v1_2
```
- Sub-versions (displayed as V1.1, V1.2 in UI)
```
v2_1
```
,
```
v2_2
```
- Sub-versions of v2

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

UIFork Widget Features

UIFork小部件功能

The

UIFork

component provides a floating UI widget that allows:

Switch versions - Click to switch between versions
Create new versions - Click "+" to create blank version
Fork versions - Fork existing version to iterate
Rename versions - Give versions meaningful names
Delete versions - Remove versions no longer needed
Promote versions - Promote version to become main component
Open in editor - Click to open version file in VS Code/Cursor

Keyboard shortcuts:

Cmd/Ctrl + Arrow Up/Down

to cycle through versions

Settings: Theme (light/dark/system), position, code editor preference

UIFork

组件提供一个悬浮UI小部件，支持以下操作：

切换版本 - 点击在不同版本间切换
创建新版本 - 点击“+”创建空白版本
衍生版本 - 基于现有版本创建衍生版本以迭代开发
重命名版本 - 为版本设置有意义的名称
删除版本 - 移除不再需要的版本
升级正式版本 - 将指定版本设为主要组件
在编辑器中打开 - 点击在VS Code/Cursor中打开版本文件

快捷键：

Cmd/Ctrl + 上/下箭头

循环切换版本

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

Custom Environment Gating

自定义环境控制

For more control over when UIFork appears:

tsx

// 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";

Useful for:

Showing on specific preview branches
Enabling for internal stakeholders on staging
Gating behind feature flags

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

tsx

// 通过NEXT_PUBLIC_ENABLE_UIFORK=true或VITE_ENABLE_UIFORK=true启用
const showUIFork =
  process.env.NODE_ENV !== "production" ||
  process.env.NEXT_PUBLIC_ENABLE_UIFORK === "true";

适用于：

在特定预览分支显示
在预发布环境为内部利益相关者启用
通过功能开关控制显示

Common Workflows

常见工作流

Starting Versioning on a Component

为组件开启版本控制

Install uifork:
```
npm install uifork
```
Add
```
<UIFork />
```
component to app root

Initialize:

npx uifork init src/components/MyComponent.tsx

Start watch server:
```
npx uifork watch
```
Use the widget to create and switch between versions

安装UIFork：
```
npm install uifork
```
将
```
<UIFork />
```
组件添加到应用根目录

初始化：

npx uifork init src/components/MyComponent.tsx

启动监听服务器：
```
npx uifork watch
```
使用小部件创建和切换版本

Creating a New Version

创建新版本

bash

undefined

bash

undefined

Create empty version

创建空白版本

npx uifork new Button

Or fork existing version

或基于现有版本创建衍生版本

npx uifork fork Button v1

undefined

npx uifork fork Button v1

undefined

Promoting a Version to Production

将版本升级为生产版本

bash

npx uifork promote Button v2

This removes all versioning and makes v2 the main component.

bash

npx uifork promote Button v2

该操作会移除所有版本控制架构，将v2设为主要组件。

How It Works

工作原理

```
ForkedComponent
```
reads active version from localStorage and renders corresponding component
```
UIFork
```
connects to watch server and displays all available versions
Selecting a version updates localStorage, triggering
```
ForkedComponent
```
to re-render
Watch server monitors file system for new version files and updates
```
versions.ts
```
automatically

```
ForkedComponent
```
从localStorage读取当前激活版本并渲染对应组件
```
UIFork
```
连接到监听服务器并显示所有可用版本
选择版本后更新localStorage，触发
```
ForkedComponent
```
重新渲染
监听服务器监控文件系统中的新版本文件，并自动更新
```
versions.ts
```