UI CLI - React + Tailwind Component Installer

A TypeScript-based CLI tool that allows developers to easily install React + Tailwind UI components into their projects.

Overview

This CLI tool enables users to add pre-built React components with Tailwind CSS styling to their projects using a simple command:

npx your-ui-lib add <component-name>

Project Structure

your-ui-lib/
├── package.json                 # Main package configuration with bin field
├── tsconfig.json               # TypeScript configuration
├── README.md                   # This file
├── dist/                       # Built JavaScript files (created after build)
│   └── cli.js
├── cli/                        # CLI source code
│   ├── index.ts               # Main CLI entry point with shebang
│   ├── commands/              # Command handlers
│   │   └── add.ts            # Add component command logic
│   ├── utils/                 # Utility functions
│   │   ├── file-operations.ts # File copying, directory creation
│   │   ├── validation.ts      # Project validation (Tailwind check)
│   │   └── cn.ts             # Conditional className utility
│   └── components/            # Component templates
│       ├── button.tsx         # Example button component
│       ├── card.tsx          # Example card component
│       └── input.tsx         # Example input component
└── scripts/                   # Build and deployment scripts
    └── build.js

Implementation Steps

Phase 1: Project Setup

1. Initialize Package Structure

   • Create package.json with proper configuration
   • Set up bin field to point to compiled CLI entry point
   • Configure TypeScript dependencies and build tools
   • Add necessary CLI libraries (commander, fs-extra, prompts, chalk)

2. TypeScript Configuration

   • Create tsconfig.json for CLI compilation
   • Configure output directory (dist/)
   • Set up proper module resolution and target ES2020+

3. Build System Setup

   • Create build script to compile TypeScript to JavaScript
   • Ensure shebang (#!/usr/bin/env node) is preserved in output
   • Set up file permissions for executable

Phase 2: CLI Core Development

4. Main CLI Entry Point (cli/index.ts)

   • Add shebang for Node.js execution
   • Initialize Commander.js for command parsing
   • Set up global CLI options and help text
   • Handle version information

5. Add Command Implementation (cli/commands/add.ts)

   • Parse component name argument
   • Validate component exists in templates
   • Create destination directory structure (components/ui/)
   • Copy component file with proper error handling
   • Display success/error messages with chalk colors

6. Utility Functions

   • File Operations (cli/utils/file-operations.ts)
     • Directory creation with recursive option
     • File copying with overwrite protection
     • Path resolution and validation
   • Project Validation (cli/utils/validation.ts)
     • Check if current directory is a valid React project
     • Validate Tailwind CSS installation
     • Verify package.json exists
   • Conditional ClassNames (cli/utils/cn.ts)
     • Implement cn utility similar to shadcn-ui
     • Combine clsx and tailwind-merge functionality

Phase 3: Component Templates

7. Create Component Templates
   • Button Component (cli/components/button.tsx)
     • Multiple variants (default, destructive, outline, secondary, ghost, link)
     • Size variations (default, sm, lg, icon)
     • Proper TypeScript interfaces
     • Use of cn utility for conditional classes
   • Card Component (cli/components/card.tsx)
     • Header, content, footer sections
     • Responsive design with Tailwind
   • Input Component (cli/components/input.tsx)
     • Form input with proper styling
     • Error states and accessibility

Phase 4: Advanced Features

8. Enhanced Validation

   • Check for existing component files (prevent overwrite)
   • Validate destination project structure
   • Provide suggestions for missing dependencies

9. Interactive Prompts

   • Confirm before overwriting existing files
   • Component variant selection
   • Destination path customization

10. Dependency Management

    • Auto-detect and suggest missing Tailwind dependencies
    • Optional automatic installation of required packages
    • Validate peer dependencies

Phase 5: Build and Distribution

11. Build Process

    • TypeScript compilation to dist/ directory
    • Preserve file permissions for CLI executable
    • Copy component templates to build output
    • Minification and optimization

12. Testing Setup

    • Local testing with npm link
    • Integration tests for file operations
    • CLI command testing framework

Development Process

Local Development Setup

1. Clone and Install Dependencies

   git clone <repository>
   cd your-ui-lib
   npm install

2. Development Build

   npm run build:dev    # Watch mode compilation

3. Local Testing

   npm link             # Link CLI globally
   cd /path/to/test-project
   npx your-ui-lib add button

Build Commands

npm run build        # Production build
npm run build:watch  # Development watch mode
npm run clean        # Clean build directory
npm run typecheck    # TypeScript type checking

NPM Publication Process

Pre-Publication Checklist

1. Version Management

   • Update version in package.json
   • Follow semantic versioning (MAJOR.MINOR.PATCH)
   • Create git tags for releases

2. Build Verification

   npm run build
   npm run test
   npm pack --dry-run   # Preview package contents

3. Package Testing

   npm link
   # Test in separate project
   npx your-ui-lib add button

Publication Steps

1. NPM Account Setup

   npm login
   npm whoami          # Verify login

2. Package Validation

   npm pack            # Create tarball for inspection
   tar -tzf your-ui-lib-*.tgz  # Inspect package contents

3. Publish to NPM

   npm publish         # Public package
   # OR
   npm publish --access public  # Ensure public access for scoped packages

4. Post-Publication

   • Verify package on npmjs.com
   • Test installation: npx your-ui-lib@latest add button
   • Update documentation with latest version

Distribution Strategy

1. Beta/RC Releases

   npm version prerelease --preid=beta
   npm publish --tag beta

2. Stable Releases

   npm version patch/minor/major
   npm publish --tag latest

Usage Documentation

Basic Usage

# Install a component
npx your-ui-lib add button

# Install multiple components
npx your-ui-lib add button card input

# Check available components
npx your-ui-lib list

# Get help
npx your-ui-lib --help

Project Requirements

• React 18+ project
• Tailwind CSS configured
• TypeScript (recommended)

Generated File Structure

After running npx your-ui-lib add button:

your-project/
├── components/
│   └── ui/
│       └── button.tsx    # Generated component
└── lib/                  # Auto-generated if needed
    └── utils.ts         # cn utility function

Component Development Guidelines

Adding New Components

1. Create Component Template

   // cli/components/new-component.tsx
   import React from 'react'
   import { cn } from '@/lib/utils'
      
   interface ComponentProps extends React.HTMLAttributes<HTMLDivElement> {
     variant?: 'default' | 'secondary'
     size?: 'sm' | 'md' | 'lg'
   }
      
   export const NewComponent = React.forwardRef<HTMLDivElement, ComponentProps>(
     ({ className, variant = 'default', size = 'md', ...props }, ref) => {
       return (
         <div
           ref={ref}
           className={cn(
             'base-classes',
             {
               'default-variant': variant === 'default',
               'secondary-variant': variant === 'secondary',
               'small-size': size === 'sm',
               'medium-size': size === 'md',
               'large-size': size === 'lg',
             },
             className
           )}
           {...props}
         />
       )
     }
   )

2. Update Component Registry

   • Add component to available components list
   • Update help documentation
   • Add usage examples

Design Principles

• Consistency: Follow established patterns from existing components
• Accessibility: Include proper ARIA attributes and keyboard navigation
• Customization: Allow easy styling overrides via className prop
• TypeScript: Full type safety with proper interfaces
• Responsive: Mobile-first responsive design approach

Future Enhancements

Planned Features

1. Advanced Configuration

   • Custom component registry
   • Theme customization
   • Component variants selection

2. IDE Integration

   • VS Code extension
   • Auto-completion for component names
   • Snippet generation

3. Framework Support

   • Next.js specific optimizations
   • Vite integration
   • Create React App compatibility

4. Community Features

   • Component marketplace
   • User-contributed components
   • Component preview generation

Technical Improvements

1. Performance

   • Faster component installation
   • Reduced bundle size
   • Caching mechanism

2. Developer Experience

   • Better error messages
   • Interactive component selection
   • Auto-update notifications

3. Testing

   • Comprehensive test coverage
   • Visual regression testing
   • Cross-platform compatibility

Contributing

Development Setup

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-component
3. Make changes and test locally
4. Submit pull request with detailed description

Component Contribution Guidelines

• Follow existing code style and patterns
• Include comprehensive TypeScript types
• Add proper documentation and examples
• Test across different project setups
• Ensure accessibility compliance

This README provides a comprehensive roadmap for building a production-ready CLI tool for React component distribution. The implementation focuses on developer experience, maintainability, and scalability.