🎭 Component Playground CLI

A powerful CLI tool for scaffolding and managing React component playgrounds. Quickly create interactive environments to showcase, test, and experiment with your UI components and their variations.

🚀 Quick Start

# Install globally
npm install -g component-playground-cli

# Or use with npx (recommended)
npx component-playground-cli init

✨ Features

• 🎯 Easy Setup: Initialize a complete component playground in seconds
• 🔄 Smart Component Discovery: Automatically scan and add existing components
• 🎨 Variation System: Create and manage multiple component variations
• ⚡ Interactive UI: Beautiful playground interface with live preview
• 🔧 TypeScript Ready: Full TypeScript support out of the box
• 📱 Universal: Works with Vite, Next.js, Create React App, Remix, and more

🏗️ Framework Support

The playground template is universal and works with any React framework:

| Framework | Support | Output Location | |-----------|---------|-----------------| | Vite | ✅ Full | src/playground/ (default) | | Create React App | ✅ Full | src/playground/ (default) | | Next.js (App Router) | ✅ Full | app/playground/ | | Next.js (Pages Router) | ✅ Full | src/playground/ + page wrapper | | Remix | ✅ Full | app/playground/ |

Next.js App Router Setup

The CLI automatically detects Next.js App Router projects and outputs to app/:

# Auto-detects Next.js App Router and creates in app/playground/
npx component-playground-cli init

Or force App Router mode manually:

npx component-playground-cli init --next-app

Final structure for Next.js App Router:

app/
├── playground/
│   ├── page.tsx                # Renamed from index.tsx
│   ├── PlaygroundCanvas.tsx
│   ├── PlaygroundSidebar.tsx
│   ├── componentsRegistry.tsx
│   └── README.md
└── playground-variations/
    ├── button-v1.tsx
    └── ...

Next.js Pages Router Setup

For Pages Router, keep files in src/ and create a page wrapper:

// pages/playground.tsx
import Playground from '../src/playground'
export default Playground

Then visit /playground in your Next.js app.

📦 Installation

Local Usage (recommended)

npx component-playground-cli init

Global Installation

npm install -g component-playground-cli
component-playground --help

🛠️ Commands

init - Initialize Playground

Creates a component playground in your current project.

component-playground init

What it does:

• Creates src/playground/ directory with all necessary files
• Sets up the playground UI (PlaygroundCanvas.tsx, PlaygroundSidebar.tsx)
• Creates componentsRegistry.tsx for component management
• Creates src/playground-variations/ directory for component variations
• Updates package.json with playground script

Note for Next.js App Router: After init, move the files to app/playground/ as shown above.

Options:

• --standalone: Create a standalone playground app (coming soon)
• -f, --force: Overwrite existing playground without prompt
• --next-app: Force Next.js App Router mode (outputs to app/ directory)

Auto-detection: The CLI automatically detects Next.js App Router projects (presence of app/ folder + next.config.*) and outputs to the correct location.

add - Add Single Component

Add a specific component to the playground registry.

component-playground add Button
component-playground add Alert --variations

What it does:

• Adds the component to componentsRegistry.tsx
• Creates a placeholder implementation
• The component will appear in the playground immediately (no variations required)
• Optionally generates variation templates (v1, v2, v3, v4) with --variations flag

Note: Variations are optional. The original component is always displayed in the playground. You can add variations later if needed.

Options:

• --variations: Automatically create variation templates

add-all - Bulk Add Components

Scan a directory and add all found components to the playground.

component-playground add-all
component-playground add-all --directory="src/components"
component-playground add-all --auto-confirm

What it does:

• Scans specified directory (default: src/components)
• Finds all TSX/JSX files (excluding tests and stories)
• Adds all components to the registry with placeholder implementations
• Generates an AI prompt for implementing the components
• Skips components already in the registry

Options:

• -d, --directory <path>: Directory to scan (default: src/components)
• --auto-confirm: Skip confirmation prompt

scan - Discover Components

Scan a directory to discover components without adding them.

component-playground scan
component-playground scan src/ui

What it does:

• Lists all components found in the directory
• Shows component names and file paths
• Useful for previewing what add-all would add

Options:

• -a, --auto-add: Automatically add all found components (coming soon)

🎮 Using the Playground

After initialization, you'll have a complete playground setup:

1. Add the Playground Route

Vite / Create React App / Remix:

// App.tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Playground from './playground';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/playground" element={<Playground />} />
        {/* Your other routes */}
      </Routes>
    </BrowserRouter>
  );
}

Next.js App Router:

After moving files to app/playground/:

// app/playground/page.tsx (renamed from index.tsx)
// No changes needed - the file already includes "use client" directive
// Just visit /playground in your browser

Next.js Pages Router:

// pages/playground.tsx
import Playground from '../src/playground'
export default Playground

2. Start Your Dev Server

npm run dev
# or
yarn dev

3. Navigate to Playground

Visit /playground route in your app

📁 Project Structure

Default (Vite/CRA)

After running init, your project will have:

src/
├── playground/
│   ├── index.tsx              # Main playground component
│   ├── PlaygroundCanvas.tsx   # Component preview area
│   ├── PlaygroundSidebar.tsx  # Component selection sidebar
│   ├── componentsRegistry.tsx  # Component registry
│   └── README.md             # Playground-specific docs
└── playground-variations/
    ├── .gitkeep
    ├── button-v1.tsx          # Component variations
    ├── button-v2.tsx
    └── ...

Next.js App Router

After moving files for Next.js App Router:

app/
├── playground/
│   ├── page.tsx               # Main playground (renamed from index.tsx)
│   ├── PlaygroundCanvas.tsx   # Component preview area
│   ├── PlaygroundSidebar.tsx  # Component selection sidebar
│   ├── componentsRegistry.tsx  # Component registry
│   └── README.md             # Playground-specific docs
└── playground-variations/
    ├── .gitkeep
    ├── button-v1.tsx          # Component variations
    ├── button-v2.tsx
    └── ...

🎨 Component Variations (Optional)

Variations are optional. The original component is always displayed in the playground without any additional setup. Variations allow you to explore different design iterations side-by-side.

If you want to add variations, they require two steps: creating the files and registering them.

Step 1: Create Variation Files

component-playground add Button --variations

This creates files in playground-variations/:

• button-v1.tsx, button-v2.tsx, button-v3.tsx, button-v4.tsx

Step 2: Register Variations

Import and register variations in variationsRegistry.ts:

import { ButtonV1Example } from "../playground-variations/button-v1";
import { ButtonV2Example } from "../playground-variations/button-v2";
import { ButtonV3Example } from "../playground-variations/button-v3";
import { ButtonV4Example } from "../playground-variations/button-v4";

export const variationsRegistry: VariationsRegistry = {
  button: [
    { name: "V1", component: ButtonV1Example },
    { name: "V2", component: ButtonV2Example },
    { name: "V3", component: ButtonV3Example },
    { name: "V4", component: ButtonV4Example },
  ],
};

The key (button) must match the filename property in componentsRegistry.tsx.

Variation File Structure

// button-v1.tsx
"use client"
import * as React from "react"

const ButtonV1 = React.forwardRef<
  HTMLButtonElement,
  React.ButtonHTMLAttributes<HTMLButtonElement>
>(({ className, ...props }, ref) => (
  <button
    ref={ref}
    className={"px-4 py-2 bg-blue-500 text-white rounded " + (className || "")}
    {...props}
  />
))
ButtonV1.displayName = "ButtonV1"

const ButtonV1Example = () => <ButtonV1>Click me!</ButtonV1>

export { ButtonV1, ButtonV1Example }

How the Variation System Works

1. Each component in componentsRegistry.tsx has a filename property (e.g., filename: "button")
2. Variation files are created in playground-variations/ with naming: {filename}-v{n}.tsx
3. Each file exports {PascalCase}V{n}Example (e.g., ButtonV1Example)
4. Variations are registered in variationsRegistry.ts with the filename as the key
5. The playground reads from the registry to display variations

Using Variations in the UI

• Click "Create Variations" to copy an AI prompt that includes:
  • File creation instructions
  • Registry import/registration code
• Click "Implement" on any variation to copy a prompt for replacing the base component

Troubleshooting Variations

• Variations don't appear:
  • Ensure filename is set in componentsRegistry.tsx
  • Ensure variations are imported and registered in variationsRegistry.ts
  • Ensure the registry key matches the filename property
  • Ensure each file exports {Name}V{n}Example

🔧 Configuration

Component Registry

The componentsRegistry.tsx file manages all playground components:

export interface ComponentRegistryItem {
  name: string;
  component: React.ComponentType<Record<string, unknown>>;
  category: string;
  description?: string;
  filename?: string;
}

export const componentsRegistry: ComponentRegistryItem[] = [
  {
    name: "Button",
    component: () => <YourButtonComponent />,
    category: "General",
    description: "Interactive button component",
    filename: "button"
  }
];

Customizing the Playground

You can customize the playground UI by modifying:

• PlaygroundCanvas.tsx - The component preview area
• PlaygroundSidebar.tsx - The component selection sidebar
• index.tsx (or page.tsx for Next.js) - The main playground layout

📝 Workflow Examples

Starting a New Vite/CRA Project

# 1. Initialize playground
npx component-playground-cli init

# 2. Add existing components
npx component-playground-cli add-all --directory="src/components"

# 3. Start dev server and visit /playground
npm run dev

Starting a New Next.js App Router Project

# 1. Initialize playground (auto-detects Next.js App Router)
npx component-playground-cli init

# 2. Add existing components
npx component-playground-cli add-all --directory="src/components"

# 3. Start dev server and visit /playground
npm run dev

The CLI automatically creates files in app/playground/ for Next.js App Router projects.

Adding New Components

# Add a single component
component-playground add Modal --variations

# Scan for new components
component-playground scan src/components

# Add all new components
component-playground add-all

Working with AI

The add-all command generates an AI prompt to help implement components:

component-playground add-all --directory="src/components"
# Copy the generated AI prompt and use it with your AI assistant

🛠️ Development

Prerequisites

• Node.js >= 16.0.0
• npm, yarn, pnpm, or bun

Building the CLI

# Clone the repository
git clone https://github.com/b1u3b01t/component-playground-cli.git
cd component-playground-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Test the CLI
component-playground --help

Project Structure

src/
├── cli.ts              # Main CLI entry point
├── commands/
│   ├── init.ts         # Initialize playground
│   ├── add.ts          # Add single component
│   ├── addAll.ts       # Bulk add components
│   └── scan.ts         # Scan for components
├── utils/              # Utility functions
└── types.ts            # TypeScript type definitions

templates/
└── react-vite/         # Universal playground template
    ├── index.tsx
    ├── PlaygroundCanvas.tsx
    ├── PlaygroundSidebar.tsx
    └── componentsRegistry.tsx

📋 Requirements

• React project with TypeScript
• Any React framework (Vite, Next.js, CRA, Remix, etc.)
• React Router (for Vite/CRA) or file-based routing (Next.js/Remix)
• Tailwind CSS (optional - templates use utility classes, but you can replace with your styling)

🤝 Contributing

See CONTRIBUTING.md for detailed guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run quality checks: npm run lint && npm run typecheck
5. Commit your changes: git commit -m "feat: ..."
6. Push to the branch: git push origin feature-name
7. Submit a pull request

📄 License

MIT License - see the LICENSE file for details.

🐛 Issues & Support

If you encounter any issues or have questions:

1. Check the existing issues
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Your environment details (Node version, framework, OS)
   • Expected vs actual behavior

🚀 Roadmap

• [x] Auto-detect Next.js App Router and output to app/ directory
• [ ] Support for additional frameworks (Vue, Svelte)
• [ ] Custom template creation
• [ ] Plugin system for extensions
• [ ] Export functionality for component showcases
• [ ] Integration with design systems

Built with ❤️ for the React community. Happy component building! 🎉