从零搭建前端组件库：一套完整的技术选型与工程化实践

csharp 体验AI代码助手 代码解读复制代码my-ui/
├── packages/
│   ├── components/         # 组件源码
│   │   ├── Button/
│   │   │   ├── index.tsx
│   │   │   ├── style.ts
│   │   │   └── __tests__/
│   │   └── ...
│   ├── theme/              # 主题变量
│   │   ├── default.css
│   │   └── dark.css
│   └── utils/              # 工具函数
├── docs/                   # 文档站点
├── scripts/                # 构建脚本
├── dist/                   # 构建产物
└── package.json

js 体验AI代码助手 代码解读复制代码// rollup.config.js
import resolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
import typescript from '@rollup/plugin-typescript'
import postcss from 'rollup-plugin-postcss'
import { terser } from 'rollup-plugin-terser'

export default [
  // ESM 输出
  {
    input: 'packages/index.ts',
    output: { dir: 'dist/es', format: 'esm' },
    plugins: [
      resolve(),
      commonjs(),
      typescript({ declaration: true, declarationDir: 'dist/es' }),
      postcss({ modules: true, extract: true }),
    ],
    external: ['react', 'react-dom'],
  },
  // UMD 输出
  {
    input: 'packages/index.ts',
    output: { dir: 'dist/umd', format: 'umd', name: 'MyUI' },
    plugins: [
      resolve(),
      commonjs(),
      typescript(),
      postcss({ modules: true }),
      terser(),
    ],
    external: ['react', 'react-dom'],
  },
]

json 体验AI代码助手 代码解读复制代码{
  "sideEffects": ["**/*.css"],
  "exports": {
    ".": "./dist/es/index.js",
    "./Button": "./dist/es/Button/index.js",
    "./Button/style": "./dist/es/Button/style.css"
  }
}

tsx 体验AI代码助手 代码解读复制代码// 全量引入
import { Button } from 'my-ui'
import 'my-ui/dist/es/index.css'

// 按需引入（需要 babel-plugin-import 或手动）
import Button from 'my-ui/es/Button'
import 'my-ui/es/Button/style.css'

bash 体验AI代码助手 代码解读复制代码npx storybook@latest init --type react

ts 体验AI代码助手 代码解读复制代码import { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../packages/**/*.stories.@(ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: '@storybook/react-vite',
}

bash 体验AI代码助手 代码解读复制代码pnpm add -w @changesets/cli
pnpm changeset init

bash 体验AI代码助手 代码解读复制代码# 开发完成，记录变更
pnpm changeset
# 更新版本号 + 生成 changelog
pnpm changeset version
# 构建并发布
pnpm build
pnpm publish

json 体验AI代码助手 代码解读复制代码{
  "name": "@your-team/my-ui",
  "version": "0.1.0",
  "main": "dist/cjs/index.js",
  "module": "dist/es/index.js",
  "types": "dist/es/index.d.ts",
  "files": ["dist"],
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

yaml 体验AI代码助手 代码解读复制代码name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/
      - run: pnpm install
      - run: pnpm build
      - run: pnpm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

csharp 体验AI代码助手 代码解读复制代码Button/
├── index.tsx          # 组件实现
├── style.ts           # 样式（或用独立的 CSS 文件）
├── interface.ts       # 类型定义
├── __tests__/         # 单元测试
│   └── index.test.tsx
└── index.ts           # 导出入口

tsx 体验AI代码助手 代码解读复制代码import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './index'

describe('Button', () => {
  it('renders correctly', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('fires onClick when clicked', () => {
    const handleClick = vi.fn()
    render(<Button onClick={handleClick}>Click me</Button>)
    fireEvent.click(screen.getByText('Click me'))
    expect(handleClick).toHaveBeenCalledTimes(1)
  })
})

tsx 体验AI代码助手 代码解读复制代码interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', loading, children, ...rest }, ref) => {
    return (
      <button
        ref={ref}
        className={clsx('my-btn', `my-btn--${variant}`, `my-btn--${size}`)}
        disabled={loading || rest.disabled}
        {...rest}
      >
        {loading && <span className="my-btn__spinner" />}
        {children}
      </button>
    )
  }
)

css 体验AI代码助手 代码解读复制代码:root {
  --my-primary: #1677ff;
  --my-primary-hover: #4096ff;
  --my-border-radius: 6px;
  --my-font-size: 14px;
  --my-spacing-unit: 4px;
}

[data-theme='dark'] {
  --my-primary: #1668dc;
  --my-primary-hover: #3c89e8;
}

css 体验AI代码助手 代码解读复制代码.my-btn--primary {
  background: var(--my-primary);
  border-radius: var(--my-border-radius);
  font-size: var(--my-font-size);
}

.my-btn--primary:hover {
  background: var(--my-primary-hover);
}

yaml 体验AI代码助手 代码解读复制代码# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'docs'
  - 'scripts'