supastarter-nextjs-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

supastarter for Next.js – Skill

supastarter for Next.js 技能指南

Expert guidance for building production-ready SaaS applications with the supastarter Next.js starter kit. Next.js only; no Vue/Nuxt content.

为使用supastarter Next.js启动套件构建可投入生产的SaaS应用提供专业指导。仅支持Next.js；不包含Vue/Nuxt相关内容。

When to Use This Skill

何时使用本技能

Use this skill when:

Building or modifying a supastarter Next.js app
Adding features (new entities, API endpoints, UI, i18n)
Working with Prisma, oRPC, Better Auth, Stripe, or the monorepo structure
Debugging setup, configuration, deployment, or troubleshooting
The user mentions supastarter Next.js, Prisma, oRPC, Better Auth, or related stack topics

在以下场景使用本技能：

构建或修改supastarter Next.js应用
添加功能（新实体、API端点、UI、i18n）
处理Prisma、oRPC、Better Auth、Stripe或单仓库结构相关工作
调试搭建、配置、部署问题或进行故障排查
用户提及supastarter Next.js、Prisma、oRPC、Better Auth或相关技术栈话题时

High-Level Workflow: New Feature

新增功能的高阶工作流

Follow this order when adding a feature:

Schema – Add or update Prisma models in
```
packages/database/prisma/schema.prisma
```
; run migrations.

Queries – Add query functions in

packages/database/prisma/queries/

and export from

queries/index.ts

API – Add oRPC procedures in
```
packages/api/modules/<name>/
```
(types, procedures, router); mount router in
```
packages/api/orpc/router.ts
```
.
UI – Add React components in
```
apps/web/
```
(e.g.
```
modules/shared/components/
```
); use shadcn, TanStack Query, session hooks.
i18n – Add translation keys in
```
packages/i18n/translations/{en,de}.json
```
.

Full walkthrough: assets/recipes/feedback-widget.md.

添加功能时请遵循以下顺序：

Schema – 在
```
packages/database/prisma/schema.prisma
```
中添加或更新Prisma模型；执行迁移。
Queries – 在
```
packages/database/prisma/queries/
```
中添加查询函数，并从
```
queries/index.ts
```
导出。
API – 在
```
packages/api/modules/<name>/
```
中添加oRPC流程（类型、流程、路由）；在
```
packages/api/orpc/router.ts
```
中挂载路由。
UI – 在
```
apps/web/
```
中添加React组件（例如
```
modules/shared/components/
```
）；使用shadcn、TanStack Query、会话钩子。
i18n – 在
```
packages/i18n/translations/{en,de}.json
```
中添加翻译键值。

完整流程演示：assets/recipes/feedback-widget.md。

Project Structure (Next.js Monorepo)

项目结构（Next.js单仓库）

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

Use package exports (e.g.

@repo/api

@repo/database

) instead of deep relative imports.

apps/web/                 # Next.js应用（App Router, app/, components/, config/, lib/）
packages/
  api/                    # Hono + oRPC (modules/, orpc/router.ts)
  auth/                   # Better Auth配置
  database/               # Prisma schema、迁移、查询
  i18n/                   # 翻译文件
  mail/                   # React Email模板、服务商配置
  storage/                # 兼容S3的存储服务
  ui/                     # 共享UI组件（shadcn）
  config/                 # 共享配置

使用包导出（例如

@repo/api

、

@repo/database

）代替深层相对导入。

References (Progressive Disclosure)

参考资料（渐进式查阅）

Load only the reference files you need. All paths are from the skill root, one level deep.

Before writing code, read references/coding-conventions.md. For copy-paste patterns and commands, use references/code-patterns.md and references/quick-reference.md.

Topic	File
Coding conventions (read first)	references/coding-conventions.md
Code patterns (examples)	references/code-patterns.md
Quick reference (commands, paths)	references/quick-reference.md
Tech stack	references/tech-stack.md
Setup, install, deps	references/setup.md
Env, config, feature flags	references/configuration.md
Debugging, common issues	references/troubleshooting.md
Prisma schema, migrations, queries	references/database-patterns.md
Hono/oRPC, procedures, router	references/api-patterns.md
Better Auth, session, protected endpoints	references/auth-patterns.md
Orgs, roles, multi-tenancy	references/organization-patterns.md
Stripe, webhooks, subscriptions	references/payments-patterns.md
AI features, models	references/ai-patterns.md
UI, theming, extensions	references/customization.md
S3-compatible, uploads	references/storage-patterns.md
Emails, templates, providers	references/mailing-patterns.md
i18n, locales, translations	references/internationalization.md
Meta, sitemap, structured data	references/seo.md
Deploy, production	references/deployment.md
Cron, background jobs	references/background-tasks.md
Analytics integration	references/analytics.md
Monitoring, errors	references/monitoring.md
E2E tests	references/e2e-testing.md

仅加载你需要的参考文件。所有路径均相对于技能根目录，仅一级深度。

编写代码前，请阅读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、流程、路由	references/api-patterns.md
Better Auth、会话、受保护端点	references/auth-patterns.md
组织、角色、多租户	references/organization-patterns.md
Stripe、Webhook、订阅	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
元数据、站点地图、结构化数据	references/seo.md
部署、生产环境	references/deployment.md
定时任务、后台作业	references/background-tasks.md
分析集成	references/analytics.md
监控、错误处理	references/monitoring.md
端到端测试	references/e2e-testing.md

Assets

资源文件

Env template: assets/env.example – environment variable keys and short comments (no secrets).
Full recipe: assets/recipes/feedback-widget.md – build a feature from DB → API → UI → i18n (feedback widget example).

环境变量模板：assets/env.example – 环境变量键值及简短说明（不含敏感信息）。
完整流程示例：assets/recipes/feedback-widget.md – 从数据库→API→UI→i18n完整构建一个功能（反馈组件示例）。

Scripts

脚本工具

generate_module.py – Scaffolds a new API module (types, procedures, router). See scripts/README.md or the Scripts section below.

How to run (from supastarter monorepo root):

bash

python scripts/generate_module.py <module-name>

Example:

python scripts/generate_module.py feedback

creates

packages/api/modules/feedback/

with

types.ts

procedures/create.ts

, and

router.ts

. Mount the router in

packages/api/orpc/router.ts

manually.

generate_module.py – 快速生成新的API模块（类型、流程、路由）。详见scripts/README.md或下方脚本章节。

运行方式（在supastarter单仓库根目录执行）：

bash

python scripts/generate_module.py <module-name>

示例：

python scripts/generate_module.py feedback

会创建

packages/api/modules/feedback/

目录，包含

types.ts

、

procedures/create.ts

和

router.ts

。需手动在

packages/api/orpc/router.ts

中挂载该路由。

Conventions (Summary)

规范摘要

TypeScript everywhere; interfaces for object shapes.
Named function exports for React components; prefer Server Components; use
```
"use client"
```
only when needed.
Forms: react-hook-form + zod; API: oRPC procedures in
```
packages/api/modules/
```
.
Use
```
@repo/*
```
package imports; do not instantiate Prisma/Drizzle in app code.
pnpm, Biome (format/lint), Turbo; Node.js ≥ 20.

Before writing code, read references/coding-conventions.md. For examples and commands: references/code-patterns.md, references/quick-reference.md, references/customization.md, references/api-patterns.md.

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

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

Official Docs

官方文档

Next.js docs (only): https://supastarter.dev/docs/nextjs
Download docs as .md: https://supastarter.dev/nextjs-docs.zip

Next.js专属文档：https://supastarter.dev/docs/nextjs
下载Markdown格式文档：https://supastarter.dev/nextjs-docs.zip