开发一个基于 Tailwind CSS 的组件库不仅能提高团队开发效率，还能确保产品的设计一致性。本节将详细介绍如何从零开始构建一个专业的组件库。

!!! note 我们使用 React 来做项目相关的演示。 !!!

项目初始化

基础配置

  1. # 创建项目
  2. mkdir my-component-library
  3. cd my-component-library
  4. pnpm init
  6. # 安装依赖
  7. pnpm add -D tailwindcss postcss autoprefixer typescript
  8. pnpm add -D @types/react @types/react-dom
  9. pnpm add -D vite @vitejs/plugin-react
  10. pnpm add -D tsup
  12. # 安装 peer 依赖
  13. pnpm add -D react react-dom

项目结构

  1. src/
  2. ├── components/
  3. │   ├── Button/
  4. │   │   ├── Button.tsx
  5. │   │   ├── Button.test.tsx
  6. │   │   └── index.ts
  7. │   ├── Input/
  8. │   └── Select/
  9. ├── hooks/
  10. │   └── useTheme.ts
  11. ├── styles/
  12. │   ├── base.css
  13. │   └── themes/
  14. ├── utils/
  15. │   └── className.ts
  16. └── index.ts

组件开发规范

组件基础模板

  1. // src/components/Button/Button.tsx
  2. import React from 'react';
  3. import { cva, type VariantProps } from 'class-variance-authority';
  5. const buttonVariants = cva(
  6.   // 基础样式
  7.   'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none',
  8.   {
  9.     variants: {
  10.       variant: {
  11.         default: 'bg-primary text-primary-foreground hover:bg-primary/90',
  12.         destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
  13.         outline: 'border border-input hover:bg-accent hover:text-accent-foreground',
  14.         secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
  15.         ghost: 'hover:bg-accent hover:text-accent-foreground',
  16.         link: 'underline-offset-4 hover:underline text-primary',
  17.       },
  18.       size: {
  19.         default: 'h-10 py-2 px-4',
  20.         sm: 'h-9 px-3 rounded-md',
  21.         lg: 'h-11 px-8 rounded-md',
  22.       },
  23.     },
  24.     defaultVariants: {
  25.       variant: 'default',
  26.       size: 'default',
  27.     },
  28.   }
  29. );
  31. export interface ButtonProps
  32.   extends React.ButtonHTMLAttributes<HTMLButtonElement>,
  33.     VariantProps<typeof buttonVariants> {}
  35. const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  36.   ({ className, variant, size, ...props }, ref) => {
  37.     return (
  38.       <button
  39.         className={buttonVariants({ variant, size, className })}
  40.         ref={ref}
  41.         {...props}
  42.       />
  43.     );
  44.   }
  45. );
  47. Button.displayName = 'Button';
  49. export { Button, buttonVariants };

类型定义

  1. // src/types/components.ts
  2. export type Variant = 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
  3. export type Size = 'default' | 'sm' | 'lg';
  5. export interface BaseProps {
  6.   className?: string;
  7.   children?: React.ReactNode;
  8. }
  10. export interface WithVariants {
  11.   variant?: Variant;
  12.   size?: Size;
  13. }

样式系统

主题配置

  1. // src/styles/theme.ts
  2. export const theme = {
  3.   colors: {
  4.     primary: {
  5.       DEFAULT: 'hsl(222.2, 47.4%, 11.2%)',
  6.       foreground: 'hsl(210, 40%, 98%)',
  7.     },
  8.     secondary: {
  9.       DEFAULT: 'hsl(210, 40%, 96.1%)',
  10.       foreground: 'hsl(222.2, 47.4%, 11.2%)',
  11.     },
  12.     destructive: {
  13.       DEFAULT: 'hsl(0, 84.2%, 60.2%)',
  14.       foreground: 'hsl(210, 40%, 98%)',
  15.     },
  16.     // ...其他颜色
  17.   },
  18.   spacing: {
  19.     // ...间距配置
  20.   },
  21.   borderRadius: {
  22.     // ...圆角配置
  23.   },
  24. };

样式工具

  1. // src/utils/className.ts
  2. import { clsx, type ClassValue } from 'clsx';
  3. import { twMerge } from 'tailwind-merge';
  5. export function cn(...inputs: ClassValue[]) {
  6.   return twMerge(clsx(inputs));
  7. }
  9. // 使用示例
  10. const className = cn(
  11.   'base-style',
  12.   variant === 'primary' && 'primary-style',
  13.   className
  14. );

组件文档

Storybook 配置

  1. // .storybook/main.js
  2. module.exports = {
  3.   stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  4.   addons: [
  5.     '@storybook/addon-links',
  6.     '@storybook/addon-essentials',
  7.     '@storybook/addon-interactions',
  8.     '@storybook/addon-a11y',
  9.   ],
  10.   framework: {
  11.     name: '@storybook/react-vite',
  12.     options: {},
  13.   },
  14. };

组件文档示例

  1. // src/components/Button/Button.stories.tsx
  2. import type { Meta, StoryObj } from '@storybook/react';
  3. import { Button } from './Button';
  5. const meta = {
  6.   title: 'Components/Button',
  7.   component: Button,
  8.   parameters: {
  9.     layout: 'centered',
  10.   },
  11.   tags: ['autodocs'],
  12. } satisfies Meta<typeof Button>;
  14. export default meta;
  15. type Story = StoryObj<typeof meta>;
  17. export const Primary: Story = {
  18.   args: {
  19.     children: 'Button',
  20.     variant: 'default',
  21.   },
  22. };
  24. export const Secondary: Story = {
  25.   args: {
  26.     children: 'Button',
  27.     variant: 'secondary',
  28.   },
  29. };

测试规范

单元测试配置

  1. // src/components/Button/Button.test.tsx
  2. import { render, screen } from '@testing-library/react';
  3. import userEvent from '@testing-library/user-event';
  4. import { Button } from './Button';
  6. describe('Button', () => {
  7.   it('renders correctly', () => {
  8.     render(<Button>Click me</Button>);
  9.     expect(screen.getByRole('button')).toHaveTextContent('Click me');
  10.   });
  12.   it('handles click events', async () => {
  13.     const handleClick = jest.fn();
  14.     render(<Button onClick={handleClick}>Click me</Button>);
  16.     await userEvent.click(screen.getByRole('button'));
  17.     expect(handleClick).toHaveBeenCalled();
  18.   });
  20.   it('applies variant styles correctly', () => {
  21.     render(<Button variant="destructive">Delete</Button>);
  22.     expect(screen.getByRole('button')).toHaveClass('bg-destructive');
  23.   });
  24. });

构建和发布

构建配置

  1. // tsup.config.ts
  2. import { defineConfig } from 'tsup';
  4. export default defineConfig({
  5.   entry: ['src/index.ts'],
  6.   format: ['cjs', 'esm'],
  7.   dts: true,
  8.   splitting: false,
  9.   sourcemap: true,
  10.   clean: true,
  11.   external: ['react', 'react-dom'],
  12.   injectStyle: false,
  13. });

包配置

  1. {
  2.   "name": "@your-org/components",
  3.   "version": "1.0.0",
  4.   "main": "./dist/index.js",
  5.   "module": "./dist/index.mjs",
  6.   "types": "./dist/index.d.ts",
  7.   "sideEffects": false,
  8.   "files": [
  9.     "dist/**"
  10.   ],
  11.   "scripts": {
  12.     "build": "tsup",
  13.     "dev": "tsup --watch",
  14.     "lint": "eslint src/",
  15.     "test": "jest",
  16.     "storybook": "storybook dev -p 6006",
  17.     "build-storybook": "storybook build"
  18.   },
  19.   "peerDependencies": {
  20.     "react": "^18.0.0",
  21.     "react-dom": "^18.0.0"
  22.   }
  23. }

CI/CD 配置

GitHub Actions

  1. # .github/workflows/ci.yml
  2. name: CI
  4. on:
  5.   push:
  6.     branches: [main]
  7.   pull_request:
  8.     branches: [main]
  10. jobs:
  11.   test:
  12.     runs-on: ubuntu-latest
  14.     steps:
  15.       - uses: actions/checkout@v2
  16.       - uses: pnpm/action-setup@v2
  17.       - uses: actions/setup-node@v2
  18.         with:
  19.           node-version: '18'
  20.           cache: 'pnpm'
  22.       - name: Install dependencies
  23.         run: pnpm install --frozen-lockfile
  25.       - name: Lint
  26.         run: pnpm lint
  28.       - name: Test
  29.         run: pnpm test
  31.       - name: Build
  32.         run: pnpm build

版本管理

Changesets 配置

  1. // .changeset/config.json
  2. {
  3.   "$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
  4.   "changelog": "@changesets/cli/changelog",
  5.   "commit": false,
  6.   "fixed": [],
  7.   "linked": [],
  8.   "access": "restricted",
  9.   "baseBranch": "main",
  10.   "updateInternalDependencies": "patch",
  11.   "ignore": []
  12. }

最佳实践

  1. 组件设计原则

    • 组件职责单一
    • 接口设计合理
    • 样式可定制
    • 可访问性支持

  2. 开发流程

    • 文档先行
    • TDD 开发
    • 代码审查
    • 持续集成

  3. 性能优化

    • 按需加载
    • Tree-shaking 支持
    • 样式优化
    • 包体积控制

  4. 维护策略

    • 版本控制
    • 更新日志
    • 问题跟踪
    • 文档更新