uifork

UIFork

UIForkは、UIコンポーネントのバージョンを管理するためのCLIツールおよびReactコンポーネントライブラリです。コンポーネントの複数のバージョンを作成し、関係者が切り替えてテストやフィードバックの収集を行い、準備ができたら最適なものを採用できます。

使用する場面

• A/Bテストや関係者からのフィードバック収集のために、Reactコンポーネントをバージョン管理したい場合
• uifork、コンポーネントのバージョン管理、またはUIのバリエーションについて言及している場合
• uiforkのCLIコマンド（init、watch、new、fork、promoteなど）のサポートが必要な場合
• Reactアプリ（Vite、Next.jsなど）でuiforkをセットアップしたい場合

インストール

npm install uifork

または、yarn、pnpm、bunを使用してください。

クイックセットアップ

1. UIForkコンポーネントを追加する

ReactアプリのルートにUIForkコンポーネントを追加します。通常は開発環境やプレビュー／ステージング環境で表示し、本番環境では表示しません。

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ファイルを生成します
• 任意でwatchサーバーを起動します（どちらの形式でも-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]

watchサーバーを起動します（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エージェント経由など）は、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>

バージョンを削除します（少なくとも1つのバージョンを残す必要があります）。

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 エージェント経由で作成した場合は、npx uifork watch を実行して versions.ts ファイルを再生成し、新しいバージョンが UIFork ウィジェットに表示されるようにします。