| name | uifork |
| description | Install and work with uifork, a CLI tool and React component library for managing UI component versions. Use when the user wants to version components, test UI variations, gather stakeholder feedback, or work with uifork commands like init, watch, new, fork, promote. |
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.
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.)
Installation
npm install uifork
Or use yarn, pnpm, or bun.
Quick Setup
1. Add UIFork Component
Add the UIFork component to your React app root. Typically shown in development and preview/staging (not production):
Vite:
import { UIFork } from "uifork";
const showUIFork = import.meta.env.MODE !== "production";
function App() {
return (
<>
<YourApp />
{showUIFork && <UIFork />}
</>
);
}
Next.js (App Router):
"use client";
import { UIFork } from "uifork";
export function UIForkProvider() {
if (process.env.NODE_ENV === "production") return null;
return <UIFork />;
}
import { UIForkProvider } from "@/components/UIForkProvider";
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<UIForkProvider />
</body>
</html>
);
}
Next.js (Pages Router):
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.
2. Initialize Component Versioning
npx uifork src/components/Button.tsx
Or use the explicit form:
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 with either form)
UIFork auto-detects whether the component uses a default export or a named export and generates the correct versioning scaffolding. If the file has multiple exported components and detection is ambiguous, specify which export to fork:
npx uifork init src/components/Button.tsx --export Button
npx uifork init src/components/Button.tsx --export default
3. Use Component Normally
import Button from "./components/Button";
import { Button } from "./components/Button";
<Button onClick={handleClick}>Click me</Button>;
CLI Commands
All commands use npx uifork:
Initialize a component (shorthand)
Initialize versioning for an existing component by passing the path directly.
npx uifork src/components/Dropdown.tsx
npx uifork src/components/Dropdown.tsx -w
Or use the explicit form:
npx uifork init src/components/Dropdown.tsx
npx uifork init src/components/Dropdown.tsx -w
npx uifork init src/components/Dropdown.tsx --export Button
watch [directory]
Start the watch server (enables UI widget communication).
npx uifork watch
npx uifork watch ./src
npx uifork watch --port 3002
npx uifork watch ./src --port 3002
When using a custom port, pass the same port to the UIFork component: <UIFork port={3002} />.
Important: After generating new version files (e.g., manually or via AI agents), run the watch command to regenerate the corresponding versions.ts files.
new <component-path> [version-id]
Create a new empty version file.
npx uifork new Button
npx uifork new Button v3
fork <component-path> <version-id> [target-version]
Fork an existing version to create a new one.
npx uifork fork Button v1
npx uifork fork Button v1 v2
npx uifork duplicate Button v1 v2
rename <component-path> <version-id> <new-version-id>
Rename a version.
npx uifork rename Button v1 v2
delete <component-path> <version-id>
Delete a version (must have at least one version remaining).
npx uifork delete Button v2
promote <component-path> <version-id>
Promote a version to be the main component and remove all versioning scaffolding.
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
File Structure
After running npx uifork src/components/Button.tsx (or 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.)
Both default exports and named exports are supported. UIFork auto-detects the export style during init and maintains it across all version files.
Version Naming
v1, v2, v3 - Major versionsv1_1, v1_2 - Sub-versions (displayed as V1.1, V1.2 in UI)v2_1, v2_2 - Sub-versions of v2
UIFork Widget Features
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
Custom Environment Gating
For more control over when UIFork appears:
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
Common Workflows
Starting Versioning on a Component
- Install uifork:
npm install uifork
- Add
<UIFork /> component to app root
- Initialize:
npx uifork src/components/MyComponent.tsx (or npx uifork init src/components/MyComponent.tsx)
- Start watch server:
npx uifork watch
- Use the widget to create and switch between versions
Creating a New Version
npx uifork new Button
npx uifork fork Button v1
Promoting a Version to Production
npx uifork promote Button v2
This removes all versioning and makes v2 the main component.
How It Works
ForkedComponent reads active version from localStorage and renders corresponding componentUIFork 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
After generating new version files: When creating version files manually or via AI agents, run npx uifork watch to regenerate the versions.ts files so the new versions appear in the UIFork widget.
