react+vite+pnpm+ts基础项目搭建

1. 项目初始化

pnpm create vite@latest my-react-app --template react-ts
cd my-react-app
pnpm install

2. 核心依赖安装

# 基础依赖
pnpm add react-router-dom @tanstack/react-query zustand axios

# UI 组件库 (任选其一)
pnpm add @mui/material @emotion/react @emotion/styled  # Material UI
# 或
pnpm add antd  # Ant Design

# 工具类
pnpm add @headlessui/react  # Headless UI
pnpm add @heroicons/react   # 图标库

# 开发工具
pnpm add eslint prettier eslint-config-prettier eslint-plugin-prettier @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-react-hooks -D
pnpm add husky lint-staged -D
pnpm add @types/node

3. 项目结构建议

src/
├─ api/              # API 请求封装
├─ assets/           # 静态资源
├─ components/       # 通用组件
│  ├─ ui/            # UI 基础组件
│  └─ shared/        # 业务共享组件
├─ features/         # 功能模块
├─ hooks/            # 自定义 hooks
├─ lib/              # 第三方库初始化/配置
├─ pages/            # 页面组件
├─ routes/           # 路由配置
├─ stores/           # 状态管理
├─ styles/           # 全局样式
├─ types/            # 类型定义
├─ utils/            # 工具函数
└─ App.tsx

4. 关键配置

vite.config.ts 优化

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    }
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://your-api-domain.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

5. 代码规范配置

.eslintrc.cjs

module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
    'plugin:prettier/recommended'
  ],
  parser: '@typescript-eslint/parser',
  plugins: ['react-refresh'],
  rules: {
    'react-refresh/only-export-components': 'warn',
    '@typescript-eslint/no-unused-vars': 'warn'
  },
}

.prettierrc

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "all",
  "jsxSingleQuote": true,
  "arrowParens": "avoid"
}

6. Git Hooks 配置

package.json 添加：

{
  "scripts": {
    "prepare": "husky install",
    "lint": "eslint . --ext ts,tsx --fix",
    "format": "prettier --write ."
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

初始化 husky：

npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

7. 推荐开发实践

1. 组件设计：

   • 使用原子设计模式组织组件
   • 组件与业务逻辑解耦
   • 合理使用Compound Components模式

2. 状态管理：

   • 优先使用 React 本地状态
   • 复杂状态使用 Zustand
   • 服务端状态使用 React Query

3. 性能优化：

   • 使用 React.memo 优化组件渲染
   • 虚拟列表优化长列表
   • 代码分割 + Suspense 延迟加载

4. TypeScript 最佳实践：

   • 严格模式开启
   • 使用 utility types (Pick, Omit, Partial等)
   • 类型定义优先使用 interface

8. 示例组件结构

// components/ui/Button.tsx
import { forwardRef } from 'react'
import clsx from 'clsx'

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary'
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = 'primary', ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={clsx(
          'rounded px-4 py-2 font-medium',
          variant === 'primary' && 'bg-blue-500 text-white',
          variant === 'secondary' && 'bg-gray-200 text-black',
          className
        )}
        {...props}
      />
    )
  }
)

Button.displayName = 'Button'

9. 启动项目

pnpm dev

10. 部署准备

pnpm build

推荐技术栈组合：

• 路由: React Router v6
• 状态管理: Zustand + React Query
• UI 库: Headless UI + 自定义 Tailwind 样式
• 表单: React Hook Form
• 测试: Vitest + Testing Library
• 监控: Sentry
• 部署: Vercel