@component-labs/react-showcase

A lightweight, fast, and developer-friendly alternative to Storybook for showcasing React components. Built with Vite for instant HMR and minimal configuration.

Features

- 🚀 Lightning fast - Powered by Vite
- 📦 Zero config - Works out of the box with auto-detection
- 🔥 Hot reload - Instant updates as you code
- 🎛️ Interactive props - Control component props in real-time
- 🎯 Type-safe - Full TypeScript support
- 🎨 Dark mode - Built-in theme switching

Quick Start

$3

Add Component Labs to your project using your preferred package manager:

``bash
npm install @component-labs/react-showcase
`

`bash
pnpm add @component-labs/react-showcase
`

`bash
yarn add @component-labs/react-showcase
`

That's it! The package will automatically build the CLI during installation via the postinstall hook.

$3

Create a showcase configuration file:

`bash
npx showcase init
`

This creates a showcase.config.ts file in your project root.

$3

Start the development server:

`bash
npx showcase dev
`

The CLI will automatically build itself before starting if needed. Your showcase will open at http://localhost:6060

$3

You can also add these to your package.json for easier access:

`json
{
"scripts": {
"showcase": "showcase dev",
"showcase:build": "showcase build"
}
}
`

Then run with:

`bash
npm run showcase
`

Configuration

Edit showcase.config.ts to customize your showcase:

`typescript
import { defineConfig } from "@component-labs/react-showcase/config";

export default defineConfig({
// Pattern to match your showcase files
include: ["src/*/.showcase.{tsx,jsx}"],

// Optional: Exclude certain paths
exclude: ["node_modules/", "dist/"],

// Optional: Custom title
title: "My Component Library",

// Optional: Port for dev server (default: 6060)
port: 6060,
});
`

Creating Showcases

$3

Create a file with the *.showcase.tsx extension:

`tsx
import { YourComponent } from "./YourComponent";

// Define metadata
export default {
title: "YourComponent",
};

// Create showcase variants
export function Basic() {
return ;
}

export function WithProps() {
return ;
}
`

$3

Add interactive props to let users experiment with your components:

`tsx
import { Button } from "./Button";
import type { Props } from "@component-labs/react-showcase";

export default {
title: "Button",
};

export function Interactive() {
return (

Click Me

);
}

// Define interactive controls
Interactive.props = {
variant: {
type: "select",
label: "Variant",
default: "primary",
options: ["primary", "secondary", "outline"],
},
size: {
type: "select",
label: "Size",
default: "medium",
options: ["small", "medium", "large"],
},
disabled: {
type: "boolean",
label: "Disabled",
default: false,
},
children: {
type: "string",
label: "Text",
default: "Click Me",
},
} satisfies Props;
`

$3

The showcase tool supports various control types:

- string - Text input field
- boolean - Checkbox toggle
- number - Number input field
- select - Dropdown with predefined options
- object - JSON object editor (advanced)
- array - Array editor (advanced)

CLI Commands

$3

Start the development server with hot reload:

`bash
npx showcase dev

Options:
-p, --port Port to run the dev server on
-c, --config Path to config file
`

$3

Build the showcase for production deployment:

`bash
npx showcase build

Options:
-c, --config Path to config file
-o, --out-dir Output directory
`

$3

Create a new showcase.config.ts file:

`bash
npx showcase init

Options:
-f, --force Overwrite existing config file
`

Example Files

The package includes complete example files that demonstrate best practices. You can find them in the examples/basic directory:

$3

A fully functional Button component with variants, sizes, and states:

`tsx
import React from "react";

export interface ButtonProps {
variant?: "primary" | "secondary" | "outline";
size?: "small" | "medium" | "large";
children: React.ReactNode;
disabled?: boolean;
onClick?: () => void;
}

export const Button: React.FC = ({
variant = "primary",
size = "medium",
children,
disabled = false,
onClick,
}) => {
const baseStyles =
"rounded font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2";

const variantStyles = {
primary:
"bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500 disabled:bg-blue-300",
secondary:
"bg-gray-600 text-white hover:bg-gray-700 focus:ring-gray-500 disabled:bg-gray-300",
outline:
"border-2 border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500 disabled:border-blue-300 disabled:text-blue-300",
};

const sizeStyles = {
small: "px-3 py-1 text-sm",
medium: "px-4 py-2 text-base",
large: "px-6 py-3 text-lg",
};

return (
className={${baseStyles} ${variantStyles[variant]} ${sizeStyles[size]}}
disabled={disabled}
onClick={onClick}
>
{children}

);
};
`

$3

Comprehensive showcase demonstrating 6 different use cases with interactive controls:

`tsx
import { Button } from "./Button";
import type { Props } from "@component-labs/react-showcase";

export default {
title: "Button",
};

export function Primary() {
return Click me;
}

export function Interactive() {
return (

Interactive Button

);
}

Interactive.props = {
variant: {
type: "select",
label: "Variant",
default: "primary",
options: ["primary", "secondary", "outline"],
},
size: {
type: "select",
label: "Size",
default: "medium",
options: ["small", "medium", "large"],
},
disabled: {
type: "boolean",
label: "Disabled",
default: false,
},
children: {
type: "string",
label: "Button Text",
default: "Interactive Button",
},
} satisfies Props;

export function AllVariants() {
return (


return (

Click Me

);
}
`

Best Practices

- Naming Convention: Use *.showcase.tsx for all showcase files
- Organization: Keep showcase files next to your components for easier maintenance
- Multiple Variants: Create multiple exports to demonstrate different states and configurations
- Interactive Props: Use prop controls to let users experiment with component behavior
- Real Use Cases: Show practical examples of how components should be used in production
- Documentation: Use descriptive names for showcase exports (e.g., DisabledState, WithIcon)

Deployment

Build and deploy to any static host:

`bash
npx showcase build
cd showcase-dist
`

Then deploy using your preferred platform:

$3

`bash
vercel
`

$3

`bash
netlify deploy --dir=showcase-dist --prod
`

$3

`bash


Add to .github/workflows/deploy.yml

- GitHub: component-labs
- NPM: @component-labs/react-showcase
- Issues: GitHub Issues
- Documentation: Run npx showcase dev` and click "Getting Started"