CLI & Copy-Paste

Overview

The Unified UI CLI lets you copy components directly into your project as local source files. Instead of importing from node_modules, you own the code — edit variants, change animations, add custom logic, or restyle anything.

This is the same workflow popularized by shadcn/ui, adapted for the Unified UI design system. The CLI handles:

• Dependency resolution — Automatically pulls in other components, utilities, and styles that a component depends on.
• npm dependency installation — Detects and installs required npm packages (Radix UI, Framer Motion, etc.).
• Import rewriting — Rewrites internal @unified-ui/* imports to local project paths (e.g., @/components/ui/*, @/lib/*).
• Client directive detection — Marks files that need "use client" for Next.js App Router.

Quick Start

npx @work-rjkashyap/unified-ui init

npx @work-rjkashyap/unified-ui add button card badge

import { Button } from "@/components/ui/button";
import { Card, CardBody } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";

export default function Page() {
	return (
		<Card>
			<CardBody className="space-y-3">
				<Badge variant="success">New</Badge>
				<Button variant="primary">Get Started</Button>
			</CardBody>
		</Card>
	);
}

// Add a new variant, change the default size,
// swap out the loading spinner, adjust colors —
// it's all local source code now.

Commands

init

Initialize an existing project for Unified UI copy-paste mode.

npx @work-rjkashyap/unified-ui init

What it does:

1. Creates a unified-ui.json config file in the project root.
2. Sets up alias paths for components, utilities, and styles.
3. Detects your package manager (npm, pnpm, yarn, bun).
4. Optionally installs base dependencies (tailwind-merge, clsx, class-variance-authority).

Flags:

init --template (Starter Kits)

Scaffold a brand-new project with a framework of your choice, fully configured with Unified UI.

# Interactive — prompts you to pick a framework
npx @work-rjkashyap/unified-ui init -t

# Specify framework and project name directly
npx @work-rjkashyap/unified-ui init -t nextjs my-app
npx @work-rjkashyap/unified-ui init --template vite-react my-app

Available templates:

You can also clone templates directly from their GitHub repos — see the Starter Kits page for full instructions.

How it works:

1. Runs the official scaffolding tool for the chosen framework (create-vite, create-next-app, create-vue, or composer create-project).
2. Installs @work-rjkashyap/unified-ui and any framework-specific dependencies.
3. Overlays Unified UI files — CSS imports, theme providers, demo pages, and config updates.
4. Initializes git with a clean commit.

add

Add one or more components, utilities, or styles to your project.

npx @work-rjkashyap/unified-ui add <name...>

Examples:

# Add a single component
npx @work-rjkashyap/unified-ui add button

# Add multiple components
npx @work-rjkashyap/unified-ui add button card badge tabs dialog

# Add everything
npx @work-rjkashyap/unified-ui add --all

# Overwrite existing files
npx @work-rjkashyap/unified-ui add button --overwrite

What it does:

1. Fetches the component's registry entry (source, dependencies, metadata).
2. Resolves the full dependency tree — other registry items + internal utilities.
3. Rewrites imports from @unified-ui/* to your project's local paths.
4. Writes files to the correct directories based on your unified-ui.json config.
5. Detects and reports npm packages that need to be installed.
6. Optionally runs your package manager to install npm dependencies.

Flags:

list

List all available components, utilities, and styles in the registry.

npx @work-rjkashyap/unified-ui list

Output:

Components (75):
  accordion, alert, alert-dialog, avatar, badge, banner, breadcrumb,
  button, calendar, card, carousel, chart, checkbox, code, collapsible,
  color-picker, combobox, command, confirm-dialog, context-menu, ...

Utilities (4):
  cn, focus-ring, contrast, merge-slots

Motion (2):
  presets, hooks

Styles (1):
  unified-ui.css

diff

Compare a local component against the latest registry version.

npx @work-rjkashyap/unified-ui diff button

This shows a unified diff of your local button.tsx against the registry's version, so you can see what's changed upstream and decide whether to merge the updates.

Flags:

Configuration

The unified-ui.json file controls where the CLI writes files and how imports are resolved.

{
	"aliases": {
		"components": "@/components/ui",
		"utils": "@/lib",
		"styles": "@/styles"
	},
	"src": true,
	"registryUrl": "https://www.unified-ui.space/r"
}

Options

Directory Mapping

With the default config and src: true, files are written to:

Dependency Resolution

When you add a component, the CLI automatically resolves its full dependency tree. There are three types of dependencies:

1. Registry Dependencies

Other Unified UI components that the added component imports. For example, dialog depends on button, so adding dialog will also add button if it's not already in your project.

dialog
├── button          (registry dependency)
├── visually-hidden (registry dependency)
└── cn              (internal utility)

2. Internal Dependencies

Shared utilities that components rely on:

3. npm Dependencies

External packages that need to be installed from npm:

The CLI detects your package manager and generates the correct install command:

# npm
npm install @radix-ui/react-dialog framer-motion

# pnpm
pnpm add @radix-ui/react-dialog framer-motion

# yarn
yarn add @radix-ui/react-dialog framer-motion

# bun
bun add @radix-ui/react-dialog framer-motion

Registry

The component registry is a collection of JSON files served from the documentation site. Each item contains:

{
	"name": "button",
	"type": "component",
	"description": "Primary action button with variants, sizes, loading state, and icon support.",
	"client": true,
	"files": [
		{
			"path": "components/ui/button.tsx",
			"content": "\"use client\";\n\nimport { cn } from \"@/lib/cn\";\n..."
		}
	],
	"dependencies": ["class-variance-authority", "tailwind-merge", "clsx"],
	"registryDependencies": ["cn", "focus-ring"],
	"internalDependencies": [],
	"exports": ["Button", "buttonVariants"]
}

Registry Endpoints

Building the Registry

If you're contributing to Unified UI or self-hosting, build the registry locally:

npm run build:registry

This scans packages/unified-ui/src/ and generates JSON files in public/r/.

Import Rewriting

When a component is copied into your project, internal imports are automatically rewritten to match your path aliases.

Before (registry source)

import { cn } from "@unified-ui/utils/cn";
import { focusRingClasses } from "@unified-ui/utils/focus-ring";
import type { FontFamilyKey } from "@unified-ui/tokens/typography";

After (your project)

import { cn } from "@/lib/cn";
import { focusRingClasses } from "@/lib/focus-ring";
import type { FontFamilyKey } from "@/lib/tokens/typography";

The rewriting is based on your unified-ui.json aliases configuration.

Using with Next.js App Router

Components that use React hooks, event handlers, or browser APIs are marked with "use client" automatically. The CLI detects this from the registry metadata and ensures the directive is present in the copied file.

"use client";

import { cn } from "@/lib/cn";
import { cva, type VariantProps } from "class-variance-authority";
import { forwardRef } from "react";

// ... component implementation

Token and utility files are pure JavaScript/TypeScript with no React dependency, so they work in both Server and Client Components.

Updating Components

To update a component to the latest registry version:

npx @work-rjkashyap/unified-ui diff button

npx @work-rjkashyap/unified-ui add button --overwrite

git diff src/components/ui/button.tsx

Comparison: npm Package vs CLI

Frequently Asked Questions

Can I use both the npm package and the CLI?

Yes. A common pattern is to install the npm package for the base system (tokens, theme, primitives) and copy specific components you need to customize heavily.

Do I need to copy the CSS file?

Yes. When using the CLI, run npx @work-rjkashyap/unified-ui add styles to copy the design system CSS file. This provides all the CSS custom properties and Tailwind @theme integration.

What happens if I add a component that depends on another?

The CLI resolves the full dependency tree automatically. If dialog needs button, both are added. If button already exists in your project, it's skipped (unless you pass --overwrite).

Can I use a custom registry URL?

Yes. Set the registryUrl field in unified-ui.json to point to your own hosted registry:

{
	"registryUrl": "https://your-internal-registry.com/r"
}

How do I contribute a component back?

If you've built a component on top of the Unified UI token system and want to contribute it:

1. Add the source file to packages/unified-ui/src/components/.
2. Export it from packages/unified-ui/src/components/index.ts.
3. Re-export from packages/unified-ui/src/index.ts.
4. Run npm run build:registry to generate the registry entry.
5. Write documentation in content/components/<name>.mdx.
6. Submit a pull request.