aapaiui

Simple UI CLI

The command-line interface for Simple UI - add beautiful components to any React project.

Installation

Global Installation (Recommended)

npm install -g @simple-ui/cli
# or
pnpm add -g @simple-ui/cli
# or
yarn global add @simple-ui/cli

Local Installation

npm install @simple-ui/cli
# or
pnpm add @simple-ui/cli
# or
yarn add @simple-ui/cli

Quick Start

1. Initialize your project

simple-ui init

This command will:

• Create a components.json configuration file
• Set up the required directory structure (src/components/ui, src/lib)
• Create a utils.ts file with the cn helper function
• List the dependencies you need to install

2. Add components

# Add a single component
simple-ui add button

# Add multiple components at once
simple-ui add button card badge input

# See what's available
simple-ui list

3. Install dependencies

Install the required dependencies shown after running init:

npm install clsx tailwind-merge class-variance-authority @radix-ui/react-slot

Commands

init

Initialize Simple UI in your project.

simple-ui init [options]

Options:

• --cwd <path> - The working directory. Defaults to current directory
• -y, --yes - Skip confirmation prompts

Example:

# Initialize in current directory
simple-ui init

# Initialize with confirmation skip
simple-ui init --yes

# Initialize in specific directory
simple-ui init --cwd ./my-project

add

Add one or more components to your project.

simple-ui add [components...] [options]

Options:

• --cwd <path> - The working directory. Defaults to current directory
• -y, --yes - Skip confirmation prompts
• -o, --overwrite - Overwrite existing files without asking
• -p, --path <path> - Custom path for components (default: src/components/ui)

Examples:

# Add a single component
simple-ui add button

# Add multiple components
simple-ui add button card badge

# Overwrite existing files
simple-ui add button --overwrite

# Add to custom path
simple-ui add button --path ./components/ui

# Skip confirmations
simple-ui add button card --yes

list

List all available components with their categories and dependencies.

simple-ui list

Output example:

📦 Available Components:

Form:
  • button (deps: @radix-ui/react-slot, class-variance-authority)
  • input

Navigation:
  • animatedtabs (deps: framer-motion)

Layout:
  • card

Display:
  • badge (deps: class-variance-authority)

Usage: simple-ui add <component-name>
Example: simple-ui add button card

Available Components

Component	Description	Category	Dependencies
button	A versatile button component with multiple variants	Form	@radix-ui/react-slot, class-variance-authority
input	A styled input field component	Form	-
card	A flexible card container with header, content, and footer	Layout	-
badge	Small status indicators and labels	Display	class-variance-authority
animatedtabs	Animated tab navigation component	Navigation	framer-motion

Configuration

The CLI uses a components.json file to configure your project:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Prerequisites

• Node.js 16.x or higher
• A React project with Tailwind CSS configured
• TypeScript (recommended)

Required Dependencies

Most components require these base dependencies:

npm install clsx tailwind-merge

Individual components may require additional dependencies:

• Button, Badge: class-variance-authority
• Button: @radix-ui/react-slot
• AnimatedTabs: framer-motion

Tailwind CSS Setup

Ensure your tailwind.config.js includes the components directory:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    // Add other paths as needed
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Project Structure

After running simple-ui init, your project structure will look like:

your-project/
├── src/
│   ├── components/
│   │   └── ui/           # Components added here
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       └── ...
│   └── lib/
│       └── utils.ts      # Utility functions
├── components.json       # Configuration file
└── package.json

Usage in Your Components

After adding components, import and use them in your React components:

import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

export function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello World</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="default">Click me</Button>
      </CardContent>
    </Card>
  );
}

Troubleshooting

CLI not found after global installation

If you get "command not found" after global installation:

• Check if the global bin directory is in your PATH
• Try reinstalling: npm uninstall -g @simple-ui/cli && npm install -g @simple-ui/cli
• Use npx: npx @simple-ui/cli list

Import paths not working

Make sure you have path aliases configured in your tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Vite projects, also add to vite.config.ts:

import path from "path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Components not styled correctly

Ensure you have:

• Tailwind CSS properly configured
• Required dependencies installed
• CSS variables defined in your globals.css

Contributing

Contributions are welcome! Please see our main Contributing Guide.

License

Licensed under the MIT license.