项目模板与最佳实践总结

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "db:generate": "drizzle-kit generate",
    "db:push": "drizzle-kit push",
    "db:studio": "drizzle-kit studio",
    "db:migrate": "drizzle-kit migrate",
    "test": "vitest",
    "test:e2e": "playwright test",
    "format": "prettier --write ."
  }
}

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "paths": { "@/*": ["./*"] },
    "plugins": [{ "name": "next" }]
  }
}

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
 
const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/settings(.*)',
  '/admin(.*)',
])
 
export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) await auth.protect()
})
 
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/webhook).*)'],
}

## 🚀 项目启动 Checklist
 
### 基础设施
- [ ] 创建 GitHub Repo
- [ ] 初始化 Next.js 项目 (create-next-app)
- [ ] 配置 TypeScript strict mode
- [ ] 安装 Tailwind CSS + shadcn/ui
- [ ] 配置路径别名 (@/*)
- [ ] 创建 .env.local 模板 (.env.example)
 
### 数据层
- [ ] 安装配置 Drizzle ORM
- [ ] 连接 PostgreSQL (Neon / Supabase / 本地)
- [ ] 创建基础 Schema (users, tenants)
- [ ] 运行首次迁移
 
### 认证
- [ ] 配置 Clerk / NextAuth
- [ ] 创建登录/注册页面
- [ ] 配置 middleware 路由保护
- [ ] 实现 Webhook 同步用户到数据库
 
### 布局
- [ ] 创建 (marketing) Route Group + 布局
- [ ] 创建 (dashboard) Route Group + 布局
- [ ] 实现 Sidebar + Header 组件
- [ ] 创建 loading.tsx / error.tsx / not-found.tsx
 
### 代码质量
- [ ] 配置 ESLint (next/core-web-vitals)
- [ ] 配置 Prettier
- [ ] 配置 Husky + lint-staged（预提交检查）
- [ ] 创建 .cursorrules / CLAUDE.md
 
### 部署
- [ ] 连接 Vercel / 配置 Docker
- [ ] 配置环境变量
- [ ] 配置域名
- [ ] 配置 Sentry 错误监控
 
### 支付（如需要）
- [ ] 注册 Stripe 账户
- [ ] 创建产品和价格
- [ ] 实现 Checkout 流程
- [ ] 配置 Webhook
 
### CI/CD
- [ ] GitHub Actions: lint + type-check + test
- [ ] Preview 部署（PR 自动部署预览）
- [ ] 生产部署（main 分支自动部署）

## 📋 功能开发 Checklist
 
### 数据层
- [ ] Schema 设计完成（含索引）
- [ ] 迁移文件已生成并测试
- [ ] tenantId 字段和外键
 
### Server Actions
- [ ] 'use server' 声明
- [ ] Zod 输入验证
- [ ] 权限检查 (requirePermission)
- [ ] tenantId 查询过滤
- [ ] 错误处理 (try-catch, { error: string })
- [ ] revalidatePath 缓存失效
 
### 前端
- [ ] page.tsx 为 Server Component
- [ ] 交互部分抽成 Client Component
- [ ] loading.tsx Skeleton
- [ ] error.tsx 错误边界
- [ ] 表单 loading + error 状态
- [ ] 移动端响应式
 
### 测试
- [ ] 单元测试覆盖 Server Actions
- [ ] 边界情况测试（空数据、权限不足、无效输入）

// 1. Server Component（默认）
// 不加 'use client'，直接 async 获取数据
export default async function ProjectsPage() {
  const projects = await getProjects()
  return <ProjectList projects={projects} />
}
 
// 2. Client Component（最小粒度）
// 只把需要交互的部分标记为 'use client'
'use client'
export function DeleteProjectButton({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition()
  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deleteProject(id))}
    >
      {isPending ? 'Deleting...' : 'Delete'}
    </button>
  )
}
 
// 3. Props 类型
// 简单 props 用 inline，复杂 props 用 type/interface
function Card({ title, children }: { title: string; children: React.ReactNode }) {}
 
interface ProjectFormProps {
  project?: Project
  onSuccess?: () => void
  mode: 'create' | 'edit'
}
function ProjectForm({ project, onSuccess, mode }: ProjectFormProps) {}

'use server'
 
import { z } from 'zod'
import { revalidatePath } from 'next/cache'
import { requirePermission } from '@/lib/auth'
 
// 1. Schema 定义在 Action 旁边
const createProjectSchema = z.object({
  name: z.string().min(1, 'Name is required').max(100),
  description: z.string().max(500).optional(),
})
 
// 2. 统一返回格式
type ActionResult<T = void> = { data?: T; error?: string }
 
// 3. Action 实现
export async function createProject(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  try {
    // 权限检查
    const { tenantId } = await requirePermission('project:create')
    
    // 输入验证
    const parsed = createProjectSchema.safeParse({
      name: formData.get('name'),
      description: formData.get('description'),
    })
    if (!parsed.success) {
      return { error: parsed.error.issues[0].message }
    }
    
    // 业务逻辑
    const [project] = await db
      .insert(projects)
      .values({ ...parsed.data, tenantId })
      .returning({ id: projects.id })
    
    // 缓存失效
    revalidatePath('/projects')
    
    return { data: { id: project.id } }
  } catch (e) {
    return { error: e instanceof Error ? e.message : 'Something went wrong' }
  }
}

// 1. 永远带 tenantId
const projects = await db
  .select()
  .from(projectsTable)
  .where(eq(projectsTable.tenantId, tenantId))  // ← 必须
  .orderBy(desc(projectsTable.updatedAt))
  .limit(20)
 
// 2. 不用 SELECT *（选需要的字段）
const projectNames = await db
  .select({ id: projectsTable.id, name: projectsTable.name })
  .from(projectsTable)
  .where(eq(projectsTable.tenantId, tenantId))
 
// 3. 分页查询用 offset + limit
const PAGE_SIZE = 20
const data = await db
  .select()
  .from(projectsTable)
  .where(eq(projectsTable.tenantId, tenantId))
  .offset((page - 1) * PAGE_SIZE)
  .limit(PAGE_SIZE)
 
// 4. 复杂查询用事务
await db.transaction(async (tx) => {
  const [project] = await tx.insert(projectsTable).values(data).returning()
  await tx.insert(auditLogsTable).values({ action: 'project.created', ... })
  return project
})

# .env.example
DATABASE_URL=postgresql://user:pass@localhost:5432/nextsaas
CLERK_SECRET_KEY=sk_test_xxx
STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx

# Commit Message（Conventional Commits）
feat(auth): add Google OAuth login
fix(billing): handle subscription cancellation edge case
refactor(db): migrate from Prisma to Drizzle
docs(readme): add deployment instructions
chore(deps): update Next.js to 15.1
test(actions): add unit tests for project CRUD
 
# 分支命名
feat/notification-system
fix/hydration-date-mismatch
refactor/auth-middleware

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check
      - run: pnpm test
      - run: pnpm build

# 一键初始化完整项目
pnpm create next-app nextsaas --typescript --tailwind --app --src-dir=false
 
cd nextsaas
 
# 安装核心依赖
pnpm add drizzle-orm @neondatabase/serverless zod
pnpm add -D drizzle-kit
 
# 安装 UI 依赖
pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest add button input card dialog form toast
 
# 安装认证
pnpm add @clerk/nextjs
 
# 安装工具
pnpm add lucide-react clsx tailwind-merge date-fns
pnpm add -D prettier eslint-config-prettier
 
# 安装测试
pnpm add -D vitest @testing-library/react playwright
 
# 创建目录结构
mkdir -p lib/{db,actions,auth,email,stripe}
mkdir -p components/{ui,forms,layouts,shared}
mkdir -p app/{\"(marketing)\",\"(auth)\",\"(dashboard)\"/projects,api/stripe/webhook}