Component Labs

A modern, accessible React component library and development toolkit.

🚀 Quick Start

# Install components via CLI (recommended)
npx @component-labs/cli init
npx @component-labs/cli add button input dialog

# Or install as npm package
npm install @component-labs/ui

📦 Packages

This monorepo contains multiple packages:

UI Components

• @component-labs/ui - React UI component library with Tailwind CSS v4 and Ariakit
  • 8 accessible components
  • Dark mode support
  • Fully themeable with CSS variables
  • Tree-shakeable exports

Developer Tools

• @component-labs/cli - CLI for installing components (shadcn/ui style)

  • Copy components directly to your project
  • Automatic CSS setup
  • TypeScript path alias configuration

• @component-labs/registry - Component metadata registry

  • Component source storage
  • Dependency tracking
  • Used by CLI for installations

Showcase Tools

• @component-labs/react-showcase - Component showcase tool for React

  • Live component preview
  • Vite-based
  • CLI included

• @component-labs/nextjs-showcase - Component showcase tool for Next.js

  • SSR support
  • Next.js App Router compatible
  • CLI included

🏗️ Project Structure

component-labs/
├── apps/
│   ├── component-labs/      # Main website
│   ├── react-showcase/      # React showcase tool (v0.5.1)
│   └── nextjs-showcase/     # Next.js showcase tool (v0.1.1)
│
└── packages/
    ├── ui/                  # Component library (v0.0.2)
    ├── cli/                 # CLI installer (v0.0.2)
    └── registry/            # Component registry (v0.0.2)

✨ Features

Accessible by Default

Built on Ariakit for WCAG 2.1 Level AA compliance out of the box.

Tailwind CSS v4

Modern utility-first styling with the latest Tailwind CSS features:

• CSS @import syntax
• CSS custom properties
• @theme directive
• Dark mode support

Two Installation Methods

CLI Installation (like shadcn/ui)

• Components copied to your project
• Full source code control
• Modify components as needed
• Import: @/components/ui/button

NPM Installation (traditional)

• Install as a package
• Easy updates via npm
• Tree-shakeable
• Import: @component-labs/ui/button

Themeable

Easy customization with CSS variables:

@theme {
  --color-primary-600: oklch(50% 0.2 250);
  --radius-md: 0.5rem;
}

🎯 For End Users

See the Usage section below for installation and usage instructions.

👨‍💻 For Contributors

Prerequisites

• Node.js >= 18
• pnpm >= 8

Development Setup

# Clone the repository
git clone https://github.com/BenDavies1218/component-labs.git
cd component-labs

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start development
pnpm dev

Repository Scripts

Build Commands

• pnpm build - Build all packages
• pnpm --filter @component-labs/ui build - Build UI package only
• pnpm --filter @component-labs/cli build - Build CLI only

Development

• pnpm dev - Start the main website
• pnpm showcase - Start React Showcase dev server
• pnpm nextjs-showcase - Start Next.js Showcase dev server

Testing

• pnpm test - Run all tests
• pnpm test:watch - Watch mode

Publishing

• See PUBLISHING.md for detailed publishing instructions
• Or run ./scripts/publish-all.sh to publish all packages

Adding a New Component

1. Create component file:

   packages/ui/src/components/your-component/YourComponent.tsx

2. Add showcase file:

   packages/ui/src/components/your-component/YourComponent.showcase.tsx

3. Add docs file:

   packages/ui/src/components/your-component/YourComponent.docs.tsx

4. Export from UI package:

   // packages/ui/src/your-component.ts
   export { YourComponent } from "./components/your-component/YourComponent";

5. Add to registry:

   # Add component metadata to packages/registry/src/registry/
   packages/registry/src/registry/your-component.ts

6. Update registry index:

   // packages/registry/src/index.ts
   import { yourComponent } from "./registry/your-component";
   
   export const registry: Registry = {
     // ... existing components
     "your-component": yourComponent,
   };

7. Update vite config:

   // packages/ui/vite.config.ts
   entry: {
     // ... existing entries
     "your-component": resolve(__dirname, "src/your-component.ts"),
   }

Using the Library

Component Labs provides two ways to use components in your project:

Option 1: CLI Installation (Recommended - shadcn/ui style)

The CLI installs component source code directly into your project, allowing full customization:

# Initialize Component Labs in your project
npx @component-labs/cli init

# Add components to your project
npx @component-labs/cli add button input dialog

# Or add all components
npx @component-labs/cli add

This will:

1. Create a components.json configuration file
2. Set up CSS imports in your global stylesheet
3. Copy component source files to your project
4. Install required dependencies

Your global CSS file should contain:

@import "tailwindcss";
@import "@component-labs/ui/base";

/* Your custom styles here */

Usage:

import { Button } from "@/components/ui/button";

function App() {
  return (
    <Button variant="default" size="md">
      Click me
    </Button>
  );
}

Option 2: NPM Package Installation

Install components as a traditional npm package:

pnpm add @component-labs/ui

Setup your global CSS:

@import "tailwindcss";
@import "@component-labs/ui/base";

Usage:

import { Button } from "@component-labs/ui/button";
import { Input } from "@component-labs/ui/input";
import { Dialog } from "@component-labs/ui/dialog";

function App() {
  return (
    <div>
      <Button variant="default" size="md">Click me</Button>
      <Input label="Email" type="email" />
    </div>
  );
}

Customizing Styles

Component Labs uses CSS custom properties for theming. Override them in your global CSS:

@import "tailwindcss";
@import "@component-labs/ui/base";

@theme {
  /* Override primary colors */
  --color-primary-600: oklch(50% 0.2 250);
  --color-primary-700: oklch(45% 0.2 250);

  /* Override border radius */
  --radius-md: 0.5rem;
}

Available Components

• button - Interactive buttons with multiple variants
• checkbox - Accessible checkbox inputs
• input - Text inputs with labels and icons
• dialog - Modal dialogs
• switch - Toggle switches
• menu - Dropdown menus
• combobox - Searchable select inputs
• data-table - Data tables with sorting and infinite scroll

🔧 Component Showcase Tools

Component Labs includes two showcase tools for documenting and testing your components:

React Showcase

A lightweight component showcase tool for Vite-based React projects.

# Install
npm install @component-labs/react-showcase

# Use CLI
npx component-showcase dev

Features:

• Live component preview
• Hot module replacement
• Automatic component discovery
• Customizable showcase configurations

Learn more →

Next.js Showcase

A showcase tool built for Next.js with SSR support.

# Install
npm install @component-labs/nextjs-showcase

# Use CLI
npx nextjs-showcase dev

Features:

• Server-side rendering support
• Next.js App Router compatible
• Automatic route generation
• SEO-friendly component documentation

Learn more →

🛠️ Tech Stack

• React 19 - UI framework
• TypeScript - Type safety
• Tailwind CSS v4 - Modern utility-first CSS
• Ariakit - Accessible component primitives
• Vite - Build tool and dev server
• Next.js 16 - React framework (for Next.js Showcase)
• Vitest - Testing framework
• pnpm - Monorepo package manager

📚 Documentation

• UI Components README - Detailed component documentation
• CLI README - CLI usage and configuration
• Publishing Guide - Package publishing instructions
• Implementation Summary - Technical implementation details

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

• UI Library, CLI, Registry: MIT License
• Showcase Tools: AGPL-3.0 License

See individual package directories for detailed license information.

🙏 Acknowledgments

• shadcn/ui - Inspiration for the CLI installation pattern
• Ariakit - Accessible component primitives
• Tailwind CSS - Utility-first CSS framework

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ by Benjamin Davies