{"id":43521173,"url":"https://github.com/pittaya-ui/ui","last_synced_at":"2026-02-03T14:15:53.071Z","repository":{"id":334780595,"uuid":"1094658914","full_name":"pittaya-ui/ui","owner":"pittaya-ui","description":"CLI to add Pittaya UI components to your React/Next.js project","archived":false,"fork":false,"pushed_at":"2026-01-26T20:06:17.000Z","size":229,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T07:35:17.421Z","etag":null,"topics":["cli","nextjs","react","tsx","ui-components","uikit"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pittaya","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pittaya-ui.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-12T02:14:45.000Z","updated_at":"2026-01-26T20:06:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pittaya-ui/ui","commit_stats":null,"previous_names":["pittaya-ui/ui"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pittaya-ui/ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pittaya-ui%2Fui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pittaya-ui%2Fui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pittaya-ui%2Fui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pittaya-ui%2Fui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pittaya-ui","download_url":"https://codeload.github.com/pittaya-ui/ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pittaya-ui%2Fui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29047558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","nextjs","react","tsx","ui-components","uikit"],"created_at":"2026-02-03T14:15:53.002Z","updated_at":"2026-02-03T14:15:53.061Z","avatar_url":"https://github.com/pittaya-ui.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pittaya UI CLI\n\nA powerful CLI to add Pittaya UI components to your React/Next.js project with intelligent dependency management and AST-based detection.\n\n## 🚀 Installation\n\nNo installation required! Use directly with `npx`:\n\n```bash\nnpx pittaya@latest init\n```\n\n**Current Version:** 0.0.9 ([View Changelog](./CHANGELOG.md))\n\n## ✨ Features\n\n- 🎯 **Smart Installation** - Automatically detects and skips already installed components\n- 🔗 **Dependency Management** - Intelligently installs component dependencies\n- 🛡️ **Preserves Customizations** - Won't overwrite your modified components\n- 📦 **Internal Dependencies** - Components can declare dependencies on other Pittaya components\n- 🤖 **AST-Based Detection** - 100% precision in detecting component dependencies using TypeScript Compiler API\n- 🗑️ **Easy Removal** - Remove components and clean up empty directories with a single command\n- ⚡ **Fast \u0026 Efficient** - Only installs what's needed\n- 🔄 **Update Management** - Check for updates and update components easily\n- 📋 **Component Discovery** - List all available and installed components with detailed information\n- 🎨 **Import Transformation** - Automatically adjusts imports to your project structure\n- 🌐 **GitHub Registry** - Components served via free CDN\n- 🔄 **Idempotent** - Safe to run multiple times\n- 🎨 **Multiple Styles** - Choose from `default`, `new-york`, or `pittaya` design styles\n- 📁 **Auto-Detection** - Automatically detects `src/` directory structure\n- 🐛 **Debug Tools** - Built-in diagnostics for troubleshooting\n\n\u003e 📖 See [ROADMAP.md](./ROADMAP.md) for upcoming features and completed milestones\n\n## 📖 Usage\n\n### Initialize Pittaya UI in your project\n\n```bash\nnpx pittaya@latest init\n```\n\nThis command will:\n\n- Create a `components.json` file with your preferences\n- Install required base dependencies\n- Configure import aliases\n- Apply style-specific CSS variables to your globals.css\n\n#### Options\n\n- `-y, --yes` - Use default settings without prompts\n\n```bash\nnpx pittaya@latest init -y\n```\n\n### Add components\n\n#### Add a specific component\n\n```bash\nnpx pittaya@latest add button\n```\n\n#### Add multiple components\n\n```bash\nnpx pittaya@latest add button badge skeleton\n```\n\n#### Add all components\n\n```bash\nnpx pittaya@latest add --all\n```\n\n#### Interactive mode\n\nIf you don't specify components, it will enter interactive mode:\n\n```bash\nnpx pittaya@latest add\n```\n\n#### Options\n\n- `-y, --yes` - Overwrite existing files without prompting\n- `-o, --overwrite` - Overwrite existing files\n- `-a, --all` - Add all components\n- `--add-missing-deps` - Automatically install missing dependencies\n\n**Flag Comparison:**\n\n| Flag                       | Overwrites Files | Auto-Installs Dependencies |\n| -------------------------- | ---------------- | -------------------------- |\n| `--yes`                    | ✅ Yes           | ❌ No                      |\n| `--add-missing-deps`       | ❌ No            | ✅ Yes                     |\n| `--yes --add-missing-deps` | ✅ Yes           | ✅ Yes                     |\n\n### ⏭️ Smart Component Installation\n\nThe CLI automatically detects if a component is already installed and **skips reinstallation** to preserve your customizations:\n\n```bash\n# Install orbit-images (which depends on button and utils)\nnpx pittaya@latest add orbit-images\n```\n\n**First run:**\n\n```\n📦 orbit-images requires: button, utils\n✓ button installed successfully!\n✓ utils installed successfully!\n✓ orbit-images installed successfully!\n```\n\n**Second run (components already installed):**\n\n```\n⏭️  orbit-images already installed, skipping...\n```\n\n**Benefits:**\n\n- 🛡️ **Preserves Customizations** - Your modified components won't be overwritten\n- ⚡ **Faster Installation** - Doesn't reinstall dependencies unnecessarily\n- 🔄 **Idempotent** - Running the same command multiple times is safe\n\n**Force Reinstallation:**\n\n```bash\nnpx pittaya@latest add button --overwrite\n```\n\n\u003e 📖 **Learn more:** See [SKIP_INSTALLED.md](./SKIP_INSTALLED.md) for detailed documentation.\n\n#### Dependency Management\n\nWhen adding a component, the CLI automatically checks for required dependencies. If any are missing, you'll see:\n\n```bash\nnpx pittaya@latest add button\n```\n\n**Output:**\n\n```\n⚠️  button requires the following dependencies:\n\n  • @radix-ui/react-slot\n\n? Do you want to install the dependencies now? › (Y/n)\n```\n\n**Skip the prompt with `--add-missing-deps`:**\n\n```bash\nnpx pittaya@latest add button --add-missing-deps\n```\n\nThis will automatically install all missing dependencies without asking.\n\n### Check for component updates\n\nCheck if your installed components have updates available in the registry:\n\n```bash\nnpx pittaya@latest diff\n```\n\nThis will show you an interactive list of installed components to check.\n\n#### Check specific components\n\n```bash\nnpx pittaya@latest diff button orbit-images\n```\n\n#### Check all installed components\n\n```bash\nnpx pittaya@latest diff --all\n```\n\n**Output:**\n\n```\n📝 Components with updates available (2):\n\n   • button\n     └─ button.tsx (modified)\n   • orbit-images\n     └─ orbit-images.tsx (modified)\n\nRun npx pittaya update \u003ccomponent\u003e to update.\n\n✅ Components up to date (1):\n\n   • utils\n```\n\n### Update components\n\nUpdate your installed components to the latest version from the registry:\n\n```bash\nnpx pittaya@latest update\n```\n\nThis will show you an interactive list of installed components to update.\n\n#### Update specific components\n\n```bash\nnpx pittaya@latest update button\n```\n\n#### Update all installed components\n\n```bash\nnpx pittaya@latest update --all\n```\n\n#### Options\n\n- `-y, --yes` - Skip confirmation prompts\n- `-f, --force` - Force update even if no changes detected\n- `-a, --all` - Update all installed components\n\n**Examples:**\n\n```bash\n# Update all components without prompts\nnpx pittaya@latest update --all --yes\n\n# Force update button (even if up to date)\nnpx pittaya@latest update button --force\n```\n\n**Output:**\n\n```\n✅ Updated 2 component(s):\n\n   • button\n   • orbit-images\n\n⏭️  Skipped 1 component(s):\n\n   • utils (already up to date)\n```\n\n### List components\n\nView all available and installed components:\n\n```bash\nnpx pittaya@latest list\n```\n\nThis will show all components from the registry, organized by category, with installation status.\n\n#### Options\n\n- `--installed` - Show only installed components\n- `--available` - Show only available components\n- `--json` - Output in JSON format\n\n### Remove components\n\nRemove installed components from your project:\n\n```bash\nnpx pittaya@latest remove button\n```\n\n#### Interactive mode\n\nIf you don't specify components, it will show a list of installed components to select for removal:\n\n```bash\nnpx pittaya@latest remove\n```\n\n#### Options\n\n- `-y, --yes` - Skip confirmation prompt\n\n### Debug component issues\n\nDiagnose why a component is not being detected as installed:\n\n```bash\nnpx pittaya@latest debug --component installation-section\n```\n\nThis will show:\n\n- Project structure (src/ vs root)\n- Resolved alias paths\n- Expected file locations\n- Actual file existence\n- Similar files found (helps identify naming issues)\n\n**Common issues it helps solve:**\n\n- File name mismatches (e.g., `InstallationSection.tsx` vs `installation-section.tsx`)\n- Wrong directory structure\n- Incorrect `components.json` configuration\n\n### View credits\n\nShow the creators and contributors of Pittaya UI:\n\n```bash\nnpx pittaya@latest credits\n```\n\n## 🎨 Available Components\n\n### Actions\n\n- **announcement-badge** - Displays an announcement badge with customizable styles\n- **button** - Displays a button or a component that looks like a button\n- **copy-button** - A button that copies content to clipboard\n\n### Forms\n\n- **checkbox** - A checkbox form control\n- **input** - Text input field\n- **label** - Form label component\n- **multi-select** - Multi-selection dropdown component\n- **radio-group** - Radio button group\n- **textarea** - Multiline text input\n\n### UI Components\n\n- **badge** - Displays a badge with customizable styles\n- **card** - Card container component\n- **carousel** - Image carousel component\n- **command** - Command palette component\n- **orbit-images** - Displays images in an orbiting motion\n- **popover** - Popover overlay component\n- **tabs** - Tab navigation component\n\n### Documentation\n\n- **installation-section** - Displays installation instructions with code snippets\n\n### Library\n\n- **utils** - Utility functions for className management\n\n\u003e 💡 **Note:** Components are available in three styles: `default`, `new-york`, and `pittaya`. Each style has its own visual design and can include different implementations.\n\n## 💡 Practical Examples\n\n### Customization Workflow\n\n```bash\n# 1. Install a component\nnpx pittaya add button\n\n# 2. Customize it in your project\n# Edit: src/components/ui/button.tsx\n# Add your own styles, logic, etc.\n\n# 3. Install other components that depend on button\nnpx pittaya add modal card dialog orbit-images\n\n# ✅ Result: Your customized button is preserved!\n# Only modal, card, dialog, and orbit-images are installed\n```\n\n### Managing Dependencies\n\n```bash\n# Install a component with multiple dependencies\nnpx pittaya add orbit-images\n\n# Output:\n# 📦 orbit-images requires: button, utils\n# ✓ button installed successfully!\n# ✓ utils installed successfully!\n# ✓ orbit-images installed successfully!\n\n# Run again - nothing is reinstalled\nnpx pittaya add orbit-images\n\n# Output:\n# ⏭️  orbit-images already installed, skipping...\n```\n\n### Force Reinstallation\n\n```bash\n# Want to reset a component to its original state?\nnpx pittaya add button --overwrite\n\n# This will:\n# ✅ Overwrite the existing button.tsx\n# ✅ Keep your other customized components intact\n```\n\n## 🔧 Configuration\n\nThe `components.json` file stores your preferences:\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/pittaya-ui/ui/main/registry/schema.json\",\n  \"style\": \"pittaya\",\n  \"rsc\": true,\n  \"tsx\": true,\n  \"tailwind\": {\n    \"config\": \"tailwind.config.ts\",\n    \"css\": \"src/app/globals.css\",\n    \"baseColor\": \"neutral\",\n    \"cssVariables\": true,\n    \"prefix\": \"\"\n  },\n  \"aliases\": {\n    \"components\": \"@/components\",\n    \"utils\": \"@/lib/utils\",\n    \"ui\": \"@/components/ui\",\n    \"lib\": \"@/lib\",\n    \"hooks\": \"@/hooks\"\n  },\n  \"iconLibrary\": \"lucide\"\n}\n```\n\n### Available Styles\n\n- **`default`** - Clean and minimal design\n- **`new-york`** - Modern and sophisticated look (inspired by shadcn/ui)\n- **`pittaya`** - Rounded and vibrant design with primary colors\n\nEach style provides different visual implementations of the same components.\n\n## 🔄 Building Registry (For Maintainers)\n\n### 🔗 Internal Dependencies\n\nComponents can declare dependencies on other Pittaya components using `internalDependencies` in the `components-index.ts` file:\n\n```typescript\n// ui/src/lib/docs/components-index.ts\n{\n  slug: \"orbit-images\",\n  name: \"Orbit Images\",\n  description: \"Displays a set of images in an orbiting motion.\",\n  category: \"Components\",\n  dependencies: [\"framer-motion\"],        // NPM dependencies\n  internalDependencies: [\"button\"],       // Pittaya components\n}\n```\n\n**When the registry is built**, `internalDependencies` are automatically added to `registryDependencies`:\n\n```json\n{\n  \"name\": \"orbit-images\",\n  \"registryDependencies\": [\n    \"button\", // ⬅️ From internalDependencies\n    \"utils\" // ⬅️ Auto-detected from code via AST\n  ]\n}\n```\n\n**When a user installs** the component, all dependencies are automatically installed:\n\n```bash\nnpx pittaya add orbit-images\n```\n\nThis will automatically install: `orbit-images` → `button` → `utils`\n\n\u003e 📖 **Learn more:** See [INTERNAL_DEPENDENCIES.md](./docs/INTERNAL_DEPENDENCIES.md) for detailed documentation.\n\n---\n\nThe registry can be built from two sources. Configure via `.env` file:\n\n### ⚙️ Configuration\n\n1. **Copy the template:**\n\n```bash\ncp .env.example .env\n```\n\n2. **Edit `.env`:**\n\n```bash\n# GitHub mode (default) - Fetches from repository\nUSE_LOCAL_UI=false\n\n# Local mode - Uses ../ui directory\n# USE_LOCAL_UI=true\n```\n\n### 🌐 GitHub Mode (Default)\n\nFetches components directly from [pittaya-ui/ui](https://github.com/pittaya-ui/ui):\n\n```bash\nnpm run build:registry\n```\n\n**Advantages:**\n\n- ✅ No need to clone UI repository\n- ✅ Always uses latest from `main` branch\n- ✅ Works in CI/CD environments\n- ✅ Completely decoupled repos\n\n### 💻 Local Mode (Development)\n\nUses local UI repo (`../ui` relative to CLI):\n\n```bash\n# Set in .env:\nUSE_LOCAL_UI=true\n\n# Then run:\nnpm run build:registry\n```\n\n**When to use:**\n\n- Testing unreleased components\n- Working on UI and CLI simultaneously\n- No internet connection\n\n### 📦 Publishing\n\n#### 1. Build the CLI\n\n```bash\ncd packages/cli\nnpm run build\n```\n\n#### 2. Test Locally\n\n```bash\n# Test the built CLI\nnpm link\npittaya --version\n```\n\n#### 3. Publish to npm\n\n```bash\nnpm run pub:release\n```\n\n✅ **Expected output:**\n\n```\n+ pittaya@0.0.9\n```\n\n#### 4. Test Published Package\n\n```bash\n# In a completely new project\nnpx create-next-app@latest test-published --typescript --tailwind --app\ncd test-published\n\n# Test with npx\nnpx pittaya@latest init -y\nnpx pittaya@latest add button\n\n# Verify\ncat src/components/ui/button.tsx\nnpm run dev\n```\n\n### Versioning\n\nFollow [Semantic Versioning](https://semver.org/):\n\n```bash\ncd packages/cli\n\n# Patch version (0.0.x) - Bug fixes\nnpm version patch\n\n# Minor version (0.x.0) - New features\nnpm version minor\n\n# Major version (x.0.0) - Breaking changes\nnpm version major\n\n# Then publish\nnpm run pub:release\n```\n\n### Update Workflow\n\n```bash\n# 1. Make changes to CLI code\n# 2. Update version\ncd packages/cli\nnpm version patch  # or minor/major\n\n# 3. Build and publish\nnpm run pub:release\n\n# 4. Commit version bump\ncd ../..\ngit add packages/cli/package.json\ngit commit -m \"chore: bump cli to 0.0.10\"\ngit push\n```\n\n### Validate Dependencies\n\nBefore publishing or committing registry changes, validate that all components have correct NPM dependencies declared:\n\n```bash\n# From root directory\nnpm run validate:deps\n```\n\nThis will check all components and report any missing dependencies:\n\n```bash\n🔍 Validating dependencies in registry components...\n\n✅ button - 2 dependencies OK\n❌ installation-section\n   Declared: [react-syntax-highlighter]\n   Detected: [lucide-react, react-syntax-highlighter, sonner]\n   Missing:  [lucide-react, sonner]\n\n📊 Summary:\n   Total components: 19\n   With errors: 1\n   Valid: 18\n```\n\n**Fix missing dependencies:**\n\n1. Open the component JSON file (e.g., `registry/styles/pittaya/components/installation-section.json`)\n2. Add missing dependencies to the `dependencies` array\n3. Run `npm run validate:deps` again to confirm\n\n**See:** [DEPENDENCY_VALIDATION.md](./docs/DEPENDENCY_VALIDATION.md) for detailed documentation.\n\n### Common Publishing Issues\n\n**Error: \"Package name already taken\"**\n\n```bash\n# Update name in packages/cli/package.json\n{\n  \"name\": \"@pittaya-ui/cli\"  // or another name\n}\n```\n\n**Error: \"Permission denied\"**\n\n```bash\nnpm whoami  # Check if logged in\nnpm logout\nnpm login\n```\n\n**Error: \"Must provide one-time password\"**\n\n```bash\n# 2FA is enabled, use OTP from authenticator app\nnpm publish --otp=123456\n```\n\n## 🎯 How It Works\n\n1. **Style-Specific Registry** - Components are organized by style (`default`, `new-york`, `pittaya`)\n2. **GitHub Registry** - Components are hosted via GitHub Raw (free CDN)\n3. **Smart Detection** - CLI checks if components are already installed before adding them\n4. **AST-Based Analysis** - Uses TypeScript Compiler API to detect dependencies with 100% accuracy\n5. **Internal Dependencies** - Components can declare dependencies on other Pittaya components\n6. **Automatic Installation** - NPM dependencies and related components are installed automatically\n7. **Skip Installed** - Already installed components are skipped to preserve customizations\n8. **Import Transformation** - Imports are adjusted according to your aliases\n9. **Auto-Detection** - Automatically detects `src/` directory structure\n10. **No Vendor Lock-in** - Components are copied to your project, you have full control\n\n### Installation Flow\n\n```\nUser runs: npx pittaya add orbit-images\n\n1. Check if orbit-images is installed ✓\n   └─ Not installed, proceed\n\n2. Fetch orbit-images from registry ✓\n   └─ Found: registryDependencies: [button, utils]\n\n3. Install dependencies:\n   ├─ Check if button is installed\n   │  └─ Not installed, install button\n   │     ├─ Check NPM deps: @radix-ui/react-slot\n   │     └─ Install to: src/components/ui/button.tsx\n   │\n   └─ Check if utils is installed\n      └─ Not installed, install utils\n         ├─ Check NPM deps: clsx, tailwind-merge\n         └─ Install to: src/lib/utils.ts\n\n4. Install orbit-images ✓\n   └─ Install to: src/components/ui/orbit-images.tsx\n\n✅ Done! All components and dependencies installed.\n```\n\n**On second run:**\n\n```\nUser runs: npx pittaya add orbit-images\n\n1. Check if orbit-images is installed ✓\n   └─ Already installed, skip!\n\n⏭️ orbit-images already installed, skipping...\n```\n\n## 🔗 Links\n\n### Documentation\n\n- [Main Documentation](https://pittaya-ui.vercel.app)\n- [Roadmap](./ROADMAP.md) - 🗺️ Future plans and completed features\n- [Changelog](./CHANGELOG.md) - Version history and changes\n- [Architecture Decision Records (ADRs)](./docs/adr/README.md) - Architectural decisions and rationale\n- [Internal Dependencies Guide](./docs/INTERNAL_DEPENDENCIES.md)\n- [Skip Installed Components Guide](./docs/SKIP_INSTALLED.md)\n\n### Repository\n\n- [GitHub - CLI \u0026 UI Monorepo](https://github.com/pittaya-ui/ui)\n- [Component Registry - Default Style](https://raw.githubusercontent.com/pittaya-ui/ui/main/registry/styles/default/index.json)\n- [Component Registry - New York Style](https://raw.githubusercontent.com/pittaya-ui/ui/main/registry/styles/new-york/index.json)\n- [Component Registry - Pittaya Style](https://raw.githubusercontent.com/pittaya-ui/ui/main/registry/styles/pittaya/index.json)\n\n## 🤝 Contributing\n\nContributions are welcome! See our:\n\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute\n- [Roadmap](ROADMAP.md) - Features we're working on\n- [ADRs](./docs/adr/README.md) - Architectural decisions\n\n## 📝 License\n\n**Proprietary Use License** - You may use this CLI in any project, but you may not modify or redistribute the source code.\n\nSee [LICENSE](./LICENSE) for full terms.\n\n© 2025 Pittaya UI - All rights reserved\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpittaya-ui%2Fui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpittaya-ui%2Fui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpittaya-ui%2Fui/lists"}