Next.js + TypeScript

完整的现代化 React 应用开发 CLAUDE.md 模板，集成 TypeScript、测试驱动开发、代码规范检查和性能优化配置。

模板内容

# CLAUDE.md
 
这个文件为Claude Code提供项目上下文和开发指导。
 
## 项目概述
 
这是一个基于Next.js 15和TypeScript的现代化React应用，采用App Router架构。
 
**技术栈**：
- Next.js 15 (App Router)
- TypeScript 5.5+
- React 18
- Tailwind CSS 3.4
- Jest + React Testing Library
- ESLint + Prettier
 
## 项目结构

app/ # Next.js App Router目录 ├── (auth)/ # 路由组：认证相关页面 ├── dashboard/ # 仪表板页面 ├── globals.css # 全局样式 ├── layout.tsx # 根布局组件 └── page.tsx # 首页组件 components/ # 可复用组件 ├── ui/ # 基础UI组件 ├── forms/ # 表单组件 └── layout/ # 布局组件 lib/ # 工具函数和配置 ├── utils.ts # 通用工具函数 ├── validations.ts # 表单验证 └── api.ts # API客户端 types/ # TypeScript类型定义 ├── global.d.ts # 全局类型 └── api.ts # API类型 public/ # 静态资源 tests/ # 测试文件 docs/ # 项目文档


## 开发命令

```bash
# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 启动生产服务器  
npm start

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 代码质量检查
npm run lint

# 运行所有测试
npm test

# 测试覆盖率
npm run test:coverage

# E2E测试
npm run test:e2e

开发规范

组件开发

所有组件必须使用TypeScript
组件文件采用PascalCase命名
每个组件都需要对应的测试文件
Props接口统一定义在组件顶部

样式规范

使用Tailwind CSS进行样式开发
自定义样式放在components对应的CSS模块中
响应式设计优先，移动端适配必需

测试策略

单元测试：所有工具函数和hooks
组件测试：用户交互和状态变化
集成测试：页面级别功能
E2E测试：关键用户流程

API集成

使用TypeScript定义所有API接口
错误处理统一在lib/api.ts中处理
使用React Query进行数据获取和缓存

性能优化

使用Next.js Image组件优化图片
实施代码分割和懒加载
使用React.memo和useMemo优化渲染
配置适当的缓存策略

部署配置

环境变量：

NEXT_PUBLIC_API_URL=
DATABASE_URL=
NEXTAUTH_SECRET=
NEXTAUTH_URL=

构建优化：

启用Gzip压缩
配置CDN和静态资源缓存
设置适当的安全头

常见任务

创建新页面

在app目录下创建对应文件夹
添加page.tsx和layout.tsx（如需要）
实施相应的测试用例

添加新组件

在components目录下创建组件文件
定义TypeScript接口
编写单元测试
更新Storybook（如果使用）

API路由开发

在app/api目录下创建路由文件
定义请求/响应类型
实施错误处理
添加API测试

故障排查

常见问题

TypeScript编译错误：检查tsconfig.json配置
样式不生效：确认Tailwind配置和导入
测试失败：检查Jest配置和模拟数据
构建失败：查看构建日志和环境变量

调试技巧

使用Next.js DevTools进行性能分析
利用React Developer Tools检查组件状态
使用浏览器开发者工具分析网络请求

最佳实践

遵循React和Next.js官方建议
保持组件小而专一
合理使用Server Components和Client Components
实施适当的SEO优化
确保无障碍访问性(a11y)

代码审查检查清单


## 使用说明

### 1. 复制配置
将上述模板内容保存为项目根目录的 `CLAUDE.md` 文件。

### 2. 个性化定制
根据项目特点调整：
- **项目描述**：更新项目概述和业务背景
- **技术栈**：根据实际使用的库和工具修改
- **目录结构**：调整为项目实际的文件结构
- **开发流程**：添加团队特有的工作流程

### 3. 环境变量配置
```bash
# .env.local 示例
NEXT_PUBLIC_API_URL=http://localhost:3000/api
DATABASE_URL=postgresql://username:password@localhost:5432/mydb
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

4. 依赖包安装

# 核心依赖
npm install next@latest react@latest react-dom@latest typescript
 
# 开发依赖
npm install -D @types/node @types/react @types/react-dom
npm install -D eslint eslint-config-next prettier
npm install -D jest @testing-library/react @testing-library/jest-dom
npm install -D tailwindcss postcss autoprefixer

模板特点

完整的开发环境

✅ 类型安全：完整的TypeScript配置和类型定义 ✅ 测试驱动：Jest + React Testing Library集成 ✅ 代码规范：ESLint + Prettier自动格式化 ✅ 样式系统：Tailwind CSS + CSS模块支持

现代化架构

✅ App Router：使用Next.js 15最新路由系统 ✅ 服务器组件：充分利用React 18特性 ✅ 性能优化：内置图片优化、代码分割等 ✅ SEO友好：服务端渲染和元数据管理

开发效率

✅ 热重载：快速开发反馈循环 ✅ 类型提示：完整的IDE支持 ✅ 自动化测试：保证代码质量 ✅ 部署就绪：Vercel等平台一键部署

💡 渐进采用：这个模板可以逐步应用到现有项目，不需要一次性重写全部代码。

高级配置

状态管理集成

// lib/store.ts - Zustand状态管理示例
import { create } from 'zustand'
 
interface AppState {
  user: User | null
  setUser: (user: User | null) => void
  theme: 'light' | 'dark'
  setTheme: (theme: 'light' | 'dark') => void
}
 
export const useAppStore = create<AppState>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
  theme: 'light',
  setTheme: (theme) => set({ theme })
}))

数据获取模式

// lib/hooks/useApi.ts - 自定义API钩子
import useSWR from 'swr'
 
export function useUser(id: string) {
  const { data, error, isLoading } = useSWR(
    `/api/users/${id}`,
    fetcher,
    { revalidateOnFocus: false }
  )
 
  return {
    user: data,
    isLoading,
    isError: error
  }
}

参考资源

模板概览 MCP 概览