supastarter-nextjs-skill

supastarter for Next.js – 技能

为使用 supastarter Next.js starter kit 构建可用于生产环境的 SaaS 应用提供专家指导。仅限 Next.js；不包含 Vue/Nuxt 内容。

何时使用此技能

在以下情况下使用此技能：

• 构建或修改 supastarter Next.js 应用
• 添加功能（新实体、API 端点、UI、i18n）
• 使用 Prisma、oRPC、Better Auth、Stripe 或 monorepo 结构
• 调试设置、配置、部署或排查问题
• 用户提到 supastarter Next.js、Prisma、oRPC、Better Auth 或相关技术栈主题

高层工作流：新功能

添加功能时，按以下顺序操作：

1. Schema – 在 packages/database/prisma/schema.prisma 中添加或更新 Prisma 模型；运行迁移。
2. Queries – 在 packages/database/prisma/queries/ 中添加查询函数，并从 queries/index.ts 导出。
3. API – 在 packages/api/modules/<name>/ 中添加 oRPC procedures（类型、procedures、router）；在 packages/api/orpc/router.ts 中挂载 router。
4. UI – 在 apps/web/ 中添加 React 组件（例如 modules/shared/components/）；使用 shadcn、TanStack Query、session hooks。
5. i18n – 在 packages/i18n/translations/{en,de}.json 中添加翻译键。

完整演练：assets/recipes/feedback-widget.md。

项目结构（Next.js Monorepo）

apps/web/                 # Next.js app (App Router, app/, components/, config/, lib/)
packages/
  api/                    # Hono + oRPC (modules/, orpc/router.ts)
  auth/                   # Better Auth config
  database/               # Prisma schema, migrations, queries
  i18n/                   # Translations
  mail/                   # React Email templates, providers
  storage/                # S3-compatible storage
  ui/                     # Shared UI (shadcn)
  config/                 # Shared config

使用 package exports（例如 @repo/api、@repo/database），而不是深层相对导入。

参考资料（渐进式披露）

只加载所需的参考文件。所有路径均相对于技能根目录，且仅深入一层。

编写代码前，请阅读 references/coding-conventions.md。有关可复制粘贴的模式和命令，请使用 references/code-patterns.md 和 references/quick-reference.md。

主题	文件
编码规范（首先阅读）	references/coding-conventions.md
代码模式（示例）	references/code-patterns.md
快速参考（命令、路径）	references/quick-reference.md
技术栈	references/tech-stack.md
设置、安装、依赖	references/setup.md
环境变量、配置、功能标志	references/configuration.md
调试、常见问题	references/troubleshooting.md
Prisma schema、迁移、查询	references/database-patterns.md
Hono/oRPC、procedures、router	references/api-patterns.md
Better Auth、session、受保护的端点	references/auth-patterns.md
组织、角色、多租户	references/organization-patterns.md
Stripe、webhooks、订阅	references/payments-patterns.md
AI 功能、模型	references/ai-patterns.md
UI、主题、扩展	references/customization.md
S3 兼容存储、上传	references/storage-patterns.md
邮件、模板、提供商	references/mailing-patterns.md
i18n、区域设置、翻译	references/internationalization.md
Meta、站点地图、结构化数据	references/seo.md
部署、生产环境	references/deployment.md
Cron、后台任务	references/background-tasks.md
分析集成	references/analytics.md
监控、错误	references/monitoring.md
E2E 测试	references/e2e-testing.md

资源

• 环境变量模板：assets/env.example – 环境变量键名和简短注释（不含机密）。
• 完整示例：assets/recipes/feedback-widget.md – 从数据库 → API → UI → i18n 构建一项功能（反馈组件示例）。

脚本

• generate_module.py – 搭建新的 API 模块骨架（类型、过程、路由器）。请参阅 scripts/README.md 或下方的“脚本”部分。

运行方法（在 supastarter monorepo 根目录中）：

python scripts/generate_module.py <module-name>

示例：python scripts/generate_module.py feedback 会创建包含 types.ts、procedures/create.ts 和 router.ts 的 packages/api/modules/feedback/。请手动将路由器挂载到 packages/api/orpc/router.ts 中。

约定（摘要）

• 全程使用 TypeScript；对象结构使用接口。
• React 组件使用具名函数导出；优先使用 Server Components；仅在需要时使用 "use client"。
• 表单：react-hook-form + zod；API：在 packages/api/modules/ 中定义 oRPC 过程。
• 使用 @repo/* 包导入；不要在应用代码中实例化 Prisma/Drizzle。
• 使用 pnpm、Biome（格式化/代码检查）、Turbo；Node.js ≥ 20。

编写代码前，请阅读 references/coding-conventions.md。示例和命令请参阅：references/code-patterns.md、references/quick-reference.md、references/customization.md、references/api-patterns.md。

官方文档

• Next.js 文档（仅此）：https://supastarter.dev/docs/nextjs
• 下载 .md 格式文档：https://supastarter.dev/nextjs-docs.zip