supastarter-nextjs-skill

supastarter for Next.js – スキル

supastarter Next.js スターターキットを使って、本番環境に対応した SaaS アプリケーションを構築するための専門的なガイダンスです。Next.js のみを対象とし、Vue/Nuxt の内容はありません。

このスキルを使う場面

次の場合に、このスキルを使用してください。

• supastarter Next.js アプリを構築または変更するとき
• 機能（新しいエンティティ、API エンドポイント、UI、i18n）を追加するとき
• Prisma、oRPC、Better Auth、Stripe、またはモノレポ構成を扱うとき
• セットアップ、設定、デプロイ、トラブルシューティングの問題をデバッグするとき
• ユーザーが supastarter Next.js、Prisma、oRPC、Better Auth、または関連するスタックのトピックに言及したとき

大まかなワークフロー：新機能

機能を追加するときは、次の順序に従ってください。

1. スキーマ – packages/database/prisma/schema.prisma に Prisma モデルを追加または更新し、マイグレーションを実行します。
2. クエリ – packages/database/prisma/queries/ にクエリ関数を追加し、queries/index.ts からエクスポートします。
3. API – packages/api/modules/<name>/ に oRPC プロシージャ（型、プロシージャ、ルーター）を追加し、packages/api/orpc/router.ts にルーターをマウントします。
4. UI – apps/web/ に React コンポーネントを追加し（例：modules/shared/components/）、shadcn、TanStack Query、セッションフックを使用します。
5. i18n – packages/i18n/translations/{en,de}.json に翻訳キーを追加します。

詳しい手順：assets/recipes/feedback-widget.md。

プロジェクト構成（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

相対パスを深くたどるインポートではなく、パッケージのエクスポート（例：@repo/api、@repo/database）を使用してください。

参考資料（段階的な開示）

必要な参考ファイルのみを読み込んでください。パスはすべてスキルのルートからの相対パスで、1 階層下にあります。

コードを書く前に、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 スキーマ、マイグレーション、クエリ	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
Cron、バックグラウンドジョブ	references/background-tasks.md
アナリティクスの統合	references/analytics.md
モニタリング、エラー	references/monitoring.md
E2E テスト	references/e2e-testing.md

アセット

• 環境変数テンプレート：assets/env.example – 環境変数のキーと簡単なコメント（シークレットは含みません）。
• 完全なレシピ：assets/recipes/feedback-widget.md – DB → API → UI → i18n の順に機能を構築します（フィードバックウィジェットの例）。

スクリプト

• generate_module.py – 新しい API モジュール（型、プロシージャ、ルーター）のひな形を生成します。scripts/README.md または以下の「スクリプト」セクションを参照してください。

実行方法（supastarter モノレポのルートから）：

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（フォーマット／lint）、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