next-forge

next-forge

next-forge は、Next.js SaaS アプリケーションを構築するための、本番運用に対応した Turborepo テンプレートです。複数のアプリ、共有パッケージ、認証、データベース、決済、メール、CMS、分析、可観測性、セキュリティなどの統合機能を備えたモノレポ構成を提供します。

クイックスタート

新しいプロジェクトを初期化します。

npx next-forge@latest init

CLI でプロジェクト名とパッケージマネージャー（bun、npm、yarn、または pnpm）の入力を求められます。インストール後、次の手順を実行します。

1. packages/database/.env の DATABASE_URL に PostgreSQL データベースを指定します（Neon を推奨）。
2. データベースのマイグレーションを実行します：bun run migrate
3. 必要に応じて、該当する .env.local ファイルにオプションの統合機能のキーを追加します。
4. 開発を開始します：bun run dev

データベース以外の統合機能はすべてオプションです。環境変数が設定されていない場合、その機能はエラーを発生させずに無効になります。

アーキテクチャの概要

モノレポにはアプリとパッケージが含まれます。アプリはデプロイ可能なアプリケーションです。パッケージは @repo/<package-name> としてインポートする共有ライブラリです。

アプリ（/apps/ 内）：

アプリ	ポート	用途
app	3000	認証が必要なメインの SaaS アプリケーション
web	3001	CMS と SEO を備えたマーケティングサイト
api	3002	Webhook、cron ジョブ用のサーバーレス API
email	3003	React Email のプレビューサーバー
docs	3004	ドキュメントサイト（Mintlify）
storybook	6006	デザインシステムのコンポーネントワークショップ
studio	3005	データベース編集用の Prisma Studio

コアパッケージ：auth、database、payments、email、cms、design-system、analytics、observability、security、storage、seo、feature-flags、internationalization、webhooks、cron、notifications、collaboration、ai、rate-limit、next-config、typescript-config。

詳しい構成については、references/architecture.md を参照してください。

主なコンセプト

環境変数

環境変数ファイルは、各アプリとパッケージと同じ場所にあります。

• apps/app/.env.local — メインアプリのキー（Clerk、Stripe など）
• apps/web/.env.local — マーケティングサイトのキー
• apps/api/.env.local — API キー
• packages/database/.env — DATABASE_URL（必須）
• packages/cms/.env.local — BaseHub トークン
• packages/internationalization/.env.local — Languine プロジェクト ID

各パッケージには、@t3-oss/env-nextjs を通じて Zod で環境変数を検証する keys.ts ファイルがあります。型安全性はビルド時に保証されます。

アプリ間の URL

ローカル URL はあらかじめ設定されています。

• NEXT_PUBLIC_APP_URL=http://localhost:3000
• NEXT_PUBLIC_WEB_URL=http://localhost:3001
• NEXT_PUBLIC_API_URL=http://localhost:3002
• NEXT_PUBLIC_DOCS_URL=http://localhost:3004

デプロイ時には、これらを本番ドメイン（例：app.yourdomain.com、www.yourdomain.com）に変更してください。

サーバーコンポーネントを優先

page.tsx と layout.tsx ファイルは常にサーバーコンポーネントです。クライアント側のインタラクティブ機能は、'use client' を指定した別ファイルに記述します。データベース、シークレット、サーバー専用 API には、サーバーコンポーネントとサーバーアクションから直接アクセスできます。

グレースフルデグラデーション

データベース以外の統合機能はすべてオプションです。クライアントではオプショナルチェーン（例：stripe?.prices.list()、resend?.emails.send()）を使用します。対応する環境変数が設定されていない場合、その機能は通知なしで無効になります。

よくあるタスク

開発の実行

bun run dev                  # All apps
bun dev --filter app         # Single app (port 3000)
bun dev --filter web         # Marketing site (port 3001)

データベースのマイグレーション

packages/database/prisma/schema.prisma を変更した後：

bun run migrate

これにより、Prisma のフォーマット、生成、db push が順に実行されます。

shadcn/ui コンポーネントの追加

npx shadcn@latest add [component] -c packages/design-system

既存のコンポーネントを更新します。

bun run bump-ui

新しいパッケージの追加

/packages/ に @repo/<name> の命名規則に従った package.json を含む新しいディレクトリを作成します。利用するアプリの依存関係に追加します。

リントとフォーマット

bun run lint                 # Check code style (Ultracite/Biome)
bun run format               # Fix code style

テスト

bun run test                 # Run tests across monorepo

ビルド

bun run build                # Build all apps and packages
bun run analyze              # Bundle analysis

デプロイ

app、web、api 用に個別のプロジェクトを作成し、それぞれを /apps/ 配下の対応するルートディレクトリに指定して、Vercel にデプロイします。環境変数はプロジェクトごとに追加するか、Vercel Team Environment Variables を使用します。

詳細なセットアップ手順とカスタマイズ方法については、以下を参照してください。

• references/setup.md — インストール、前提条件、環境変数、データベースと Stripe CLI のセットアップ
• references/packages.md — 各パッケージの詳細なドキュメント
• references/customization.md — プロバイダーの切り替え、機能の拡張、デプロイ設定
• references/architecture.md — モノレポの全体構成、Turborepo パイプライン、スクリプト