Building Component Libraries

Introduction

A component library is the implementation layer of your design system — reusable React components that enforce consistency. Building one well means your team ships faster with fewer visual bugs.

But a component library requires thoughtful API design, built-in accessibility, documentation, and a publishing pipeline. The architecture decisions you make early determine whether it scales.

This guide covers project setup, component patterns, build tooling, and publishing as an npm package.

Key Concepts

Component API Design with CVA

typescript

import { forwardRef, type ComponentPropsWithRef } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
        ghost: 'hover:bg-gray-100',
        destructive: 'bg-red-600 text-white hover:bg-red-700',
      },
      size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6 text-base' },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
);

interface ButtonProps extends ComponentPropsWithRef<'button'>, VariantProps<typeof buttonVariants> {
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant, size, isLoading, children, className, ...props }, ref) => (
    <button ref={ref} className={buttonVariants({ variant, size, className })}
      disabled={isLoading || props.disabled} {...props}>
      {isLoading && <Spinner className="mr-2" />}
      {children}
    </button>
  )
);

Build Configuration

typescript

// tsup.config.ts
import { defineConfig } from 'tsup';
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom'],
  sourcemap: true,
  treeshake: true,
});

Practical Examples

1. Compound Component Pattern

typescript

const CardContext = createContext<{ variant: string }>({ variant: 'default' });

function Card({ variant = 'default', children, className }: CardProps) {
  return (
    <CardContext.Provider value={{ variant }}>
      <div className={cn('rounded-lg border bg-white p-6', className)}>{children}</div>
    </CardContext.Provider>
  );
}
Card.Header = ({ children }) => <div className="mb-4">{children}</div>;
Card.Title = ({ children }) => <h3 className="text-lg font-semibold">{children}</h3>;

// Usage
<Card>
  <Card.Header><Card.Title>Dashboard</Card.Title></Card.Header>
  <p>Content</p>
</Card>

2. Polymorphic Component

typescript

type AsProp<C extends React.ElementType> = { as?: C };

export function Text<C extends React.ElementType = 'p'>({
  as, children, className, ...props
}: AsProp<C> & Omit<React.ComponentPropsWithRef<C>, 'as'> & { className?: string }) {
  const Component = as || 'p';
  return <Component className={className} {...props}>{children}</Component>;
}

<Text>Paragraph</Text>
<Text as="h1" className="text-4xl font-bold">Heading</Text>
<Text as="span">Inline</Text>

3. Project Structure

plain

my-ui/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   └── index.ts
│   │   ├── Input/
│   │   └── Dialog/
│   ├── tokens/
│   └── index.ts          # Public API
├── tsup.config.ts
└── package.json

Best Practices

✅ Extend native HTML element props — don't rebuild what the browser gives you
✅ Use forwardRef for all components — consumers need ref access
✅ Use CVA for type-safe variant management
✅ Export types alongside components for TypeScript consumers
✅ Keep the API surface small — fewer props, more composition
❌ Don't bundle React — mark it as a peer dependency
❌ Don't couple to a specific styling solution — support className overrides

Common Pitfalls

Making components too opinionated — hard to customize for edge cases
Not testing with screen readers — accessibility bugs sneak in
Barrel exports causing bundle issues — use tree-shakeable ESM
Breaking changes without semver — consumers lose trust

Design Tokens Complete Guide — The foundation your components consume
Storybook Setup Guide — Document and test components visually
Design System Versioning — Manage releases and breaking changes
Design System Documentation — Make your library easy to adopt

Building Component Libraries

Introduction

Key Concepts

Component API Design with CVA

Build Configuration

Practical Examples

1. Compound Component Pattern

2. Polymorphic Component

3. Project Structure

Best Practices

Common Pitfalls

Related Guides