scaffold-nextjs

Next.js のスキャフォールド

ツール一式、GitHub、Vercel デプロイを備えた Next.js turborepo をスキャフォールドします。

• 対象： 新しい Next.js turborepo をエンドツーエンドで立ち上げます。アプリの作成、Blode UI、ultracite/oxlint/shadcn を使った Ultracite、turborepo への変換、GitHub、Vercel が含まれます。
• 対象外： TypeScript CLI や npm パッケージのスキャフォールド（scaffold-cli を使用）、既存アプリのフォルダー構成やモジュールの契約の設計（codebase-architecture を使用）、既存アプリ内のページの構築、ビジュアルの方向性やカラーパレットの選択（ui-design を使用）。

リファレンスには、標準の技術スタックと依存関係の順序が記載されています。バージョンに依存するフラグは、インストール済み CLI と同梱ドキュメントで確認してください。実績のあるテンプレートに互換性の問題がある場合は、古いフラグを無理に使わず、テンプレートを更新してください。リファレンスに答えがない Next.js に関する疑問が生じた場合は、学習データではなく、アプリ内の同梱ドキュメント node_modules/next/dist/docs/ を参照してください（インストール済みバージョンに対応しています）。

リファレンスファイル

ファイル	読むタイミング
references/app-setup.md	フェーズ 2：create-next-app のフラグ、TypeScript 7 へのアップグレード、Instant Navigations の設定と apps/web/AGENTS.md のルールブロック、shadcn + Blode レジストリ、アイコン、Agentation、ultracite/oxlint/shadcn を使った Ultracite 7.12 以降、apps/web/ への移動
references/turbo-configs.md	フェーズ 6：ルートの package.json、pnpm-workspace.yaml、turbo.json、ルートの lefthook.yml、.gitignore、knip.json、ワークスペーススクリプト、next.config.ts、ルートとアプリの AGENTS.md
references/deploy-and-launch.md	フェーズ 7 と 8：GitHub、Vercel、CI ワークフロー、metadataBase、検証、security.txt、favicon、OG 画像、検証チェックリスト

スキャフォールドのワークフロー

進捗を記録するため、このチェックリストをコピーしてください。

Scaffold progress:
- [ ] Phase 1: Gather project info
- [ ] Phase 2: Create Next.js app
- [ ] Phase 2.1: Upgrade to TypeScript 7
- [ ] Phase 2.2: Turn on Instant Navigations
- [ ] Phase 3: Install Blode UI components and icons
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 5.1: Enable ultracite/oxlint/shadcn
- [ ] Phase 6: Convert to Turborepo
- [ ] Phase 7: GitHub and Vercel setup
- [ ] Phase 8: Pre-launch checklist
- [ ] Validation: run the checklist in deploy-and-launch.md

フェーズ 1：プロジェクト情報の収集

ユーザーから以下の情報を収集します（不足している項目だけを質問してください）。

変数	例	デフォルト	使用箇所
{{name}}	acme-web	なし（必須）	ルートの package.json、ディレクトリ名、README
{{description}}	Marketing site for Acme	なし（必須）	アプリの package.json、README
{{repo}}	acme-corp/acme-web	なし（必須）	GitHub リモート URL
{{domain}}	acme.com	なし（未指定の場合は確認）	Vercel カスタムドメイン、metadataBase
{{author}}	Your Name	なし（必須）	package.json の author
{{year}}	2026	現在の年	LICENSE

フェーズ 2：Next.js アプリの作成

references/app-setup.md に記載された create-next-app コマンドを、書かれているとおりに実行してください（リンター、React Compiler、パッケージマネージャーのフラグが固定されています）。サーバーが報告したポートでアプリが読み込まれることを確認してください。3000 番ポートが使用中の場合は、タスク専用の空きポートを使用してください。

フェーズ 2.1：TypeScript 7 へのアップグレード

references/app-setup.md の TypeScript 7 セクションに従い、typescript@^7 をインストールして、pnpm run build が tsc で型チェックを実行することを確認してください。設定ファイルの追加は不要です。

フェーズ 2.2：Instant Navigations を有効にする

references/app-setup.md の Instant Navigations セクションに従い、next.config.ts で cacheComponents、partialPrefetching、experimental.turbopackRustReactCompiler を設定してください。ここでの対応は低コストですが、後からでは高コストになるため、ルートを作成する前に行ってください。フェーズ 3 の前に、その後に記載されている Instant Navigations のルールブロックを読んでください。このルールはすべてのページの作成方法を定めており、フェーズ 5.1 で AGENTS.md に追加します。

フェーズ 3：Blode UI コンポーネントとアイコンのインストール

references/app-setup.md の Blode UI セクションに従い、shadcn init を実行し、@blode 名前空間を登録して、components.json で iconLibrary を設定し、blode-icons-react をインストールしてからコンポーネントを追加してください。

フェーズ 4：Agentation のインストール

references/app-setup.md の Agentation セクションに従い、パッケージをインストールして、開発時のみのガードを含むクライアントの DevTools コンポーネントを追加し、app/layout.tsx でレンダリングしてください。必要に応じて、@next/third-parties を使って Google Analytics を追加できます。

フェーズ 5：Ultracite のインストール

references/app-setup.md の Ultracite セクションに従い、記載されている正確なフラグをすべて指定して ultracite@latest init を実行します。--js-plugins @shadcn/lint も含めてください（Ultracite ≥ 7.12）。pnpm exec ultracite fix と pnpm exec ultracite check で検証します。書き込まれる lefthook.yml は一時的なもので、フェーズ 6 でルートレベルのファイルに置き換えます。

フェーズ 5.1：ultracite/oxlint/shadcn を有効にする

references/app-setup.md の ultracite/oxlint/shadcn セクションに従い、初期化によって import shadcn from "ultracite/oxlint/shadcn" が、core/next/react とともに extends に書き込まれたことを確認します。書き込まれていない場合は、そのインポート（および jsPlugins: shadcn.jsPlugins）を追加します。jsPlugins: ["@shadcn/lint"] や、スターター専用の no-restyle ルールを独自に作成しないでください。このプリセットはすでに **/components/ui/** 内で shadcn/no-restyle を無効にしています。aliases.ui が異なるパスの場合に限り、一致するオーバーライドを追加します。

フェーズ 6：Turborepo に移行する

アプリを apps/web/ に移動し（コマンドは references/app-setup.md の末尾を参照）、その後 references/turbo-configs.md に従います。

1. テンプレートからルートの package.json、pnpm-workspace.yaml、turbo.json、lefthook.yml、knip.json、.gitignore を生成します。apps/web/lefthook.yml を削除します。git が読み込むのは .git の隣にあるコピーだけです。apps/web/pnpm-workspace.yaml にビルドスクリプトの設定があればルートのファイルに移動してから、削除します。
2. apps/web/package.json のスクリプトを Turbo 対応のブロックに更新し、prepare スクリプトを削除します（フックはルートのものがインストールします）。
3. apps/web/next.config.ts に reactCompiler: true、cacheComponents: true、partialPrefetching: true が引き続き設定されていることを確認します。
4. テンプレートからルートの AGENTS.md を作成します。フェーズ 5.1 の Instant Navigations とデザインシステムの lint セクションは、Next が管理するマーカーの外側にある apps/web/AGENTS.md に残します。
5. ルートで pnpm install を実行し、次にコーディングエージェントのシェルから pnpm run dev を一度実行します。Next 16.3 は環境内のコーディングエージェントを検出すると、管理対象の nextjs-agent-rules ブロックを apps/web/AGENTS.md に追加します（ジェネレーターによっては CLAUDE.md のラッパーも作成されます）。AGENTS.md をコミットし、重複する CLAUDE.md ラッパーがあれば削除します。通常のターミナルからは何も書き込まれませんが、問題ありません。このブロックはエージェントの初回実行時に追加されます。
6. ルートで pnpm run check、pnpm run build、pnpm exec lefthook run pre-commit --all-files が成功することを確認し、次に pnpm --filter web start を実行して、本番ビルドのホームページを読み込みます。

フェーズ 7：GitHub と Vercel のセットアップ

references/deploy-and-launch.md に従い、gh で GitHub リポジトリを作成し、Vercel にデプロイして、{{domain}} を関連付けます。

フェーズ 8：ローンチ前チェックリスト

references/deploy-and-launch.md に従い、CI ワークフローを追加し、metadataBase を https://{{domain}} に設定し、サイトを Search Console と Bing に登録して、security.txt、favicon パッケージ、OG 画像を追加します。その後、ファイル末尾にある検証チェックリストを実行します。すべての検証項目に合格した場合にのみ完了です。「サイトが読み込める」だけでは十分な根拠になりません。

プレースホルダーの参照

テンプレートでは {{variable}} 構文を使います。フェーズ 7 の前に、置き換え忘れたプレースホルダーがないか確認します。

grep -rn '{{' --include='*.json' --include='*.ts' --include='*.tsx' --include='*.md' --include='*.yml' .

package.json に {{name}} が残っていると pnpm install が失敗します（invalid-name エラー）。メタデータに {{domain}} が残っていると、壊れた OG URL が公開されます。ルートの package.json テンプレートには、フェーズ 1 で収集されないプレースホルダーが 2 つあります。{{ultracite_version}} は ultracite init が apps/web/package.json に書き込んだ ultracite エントリーからコピーし、{{pnpm_version}} には pnpm --version の出力を指定します。

注意点

• src/ ディレクトリはありません。スキャフォールドでは --no-src-dir を使用しているため、後から src/ を追加すると @/* エイリアスとすべての shadcn コンポーネントのパスが壊れます。
• output: "standalone" は絶対に追加しないでください。これはセルフホスト用であり、Vercel では .next/next-server.js.nft.json が書き込まれなくなるため、すべてのページをビルドした後、Vercel の onBuildComplete で失敗します。
• Turbopack のキャッシュ設定は追加しないでください。turbopackFileSystemCacheForDev、turbopackFileSystemCacheForBuild、およびメモリの削除（'auto'）は、16.3 でデフォルトで有効になっています。
• ESLint や Prettier は使用しないでください。リンティングとフォーマットは Ultracite が Oxlint + Oxfmt を通じて管理します。余計な .eslintrc があると、エディターの動作が lefthook の pre-commit フックと一致しなくなります。
• リンティングとフォーマットはワークスペースのスクリプトから実行してください。ルートで pnpm run check / pnpm run fix を実行するか（turbo が apps/web 内で実行します）、apps/web から pnpm exec ultracite check を実行します。リポジトリのルートで ultracite、oxlint、または oxfmt を実行すると、その場所に oxlint.config.ts が見つからず、デフォルト設定でリンティングされるため、フックの動作と一致せず、shadcn プリセットも適用されません。ultracite fix の後に残るデザインシステム関連の指摘は、apps/web から pnpm exec ultracite fix --codex（または --claude）で修正できます。
• Git フックを手動で追加しないでください。フックは Lefthook が管理します。husky など別のフックマネージャーを使うと、処理が二重に実行されたり、修正がスキップされたりします。
• pnpm は依存関係をルートの node_modules にホイストしないため、ツールはそれを宣言しているワークスペース内でのみ解決されます。oxlint、oxfmt、@shadcn/lint は apps/web 内で pnpm exec を通じて実行してください（lefthook の root: と turbo のスクリプトではすでにそうなっています）。ルートに追加してはいけません。
• アプリの依存関係をルートの package.json に追加しないでください（ルートに置くのは turbo、ultracite、lefthook のみです）。追加するとワークスペースの分離と turbo のキャッシュキーが壊れます。@shadcn/lint は oxlint.config.ts とともに apps/web に置きます。設定解決にずれが生じないよう、ルートと apps/web で同じバージョンの ultracite（≥ 7.12）を固定してください。
• apps/web/ を手作業で作成しないでください。最初にルートでスキャフォールドを作成し、Phase 6 で移動してください。手作業で作成すると、create-next-app のデフォルト設定（Tailwind の配線、エイリアス設定）が適用されません。
• node --test はテストファイルを直接実行するため、@/ エイリアスは解決されません。テストファイルと、それらがインポートするモジュールでは相対パスを使用してください。また、テストスクリプトでは個別のファイルを指定せず、lib/**/*.test.ts をグロブで指定してください。そうしないと、新しいテストが実行されないまま、チェックが成功したと報告されます。tsc のビルドではテストファイルも含めてプロジェクト全体をチェックします。型エラーがない状態にするか、tsconfig.json の exclude に **/*.test.ts を追加してください。

スキルの引き継ぎ

タイミング	実行
デプロイ後に SEO を最適化する	seo
リリース前に UI 品質を監査する	ui-design（Audit モード）
リリース前にモーションとアニメーションを追加する	ui-animation

メンテナンス専用です。evals/evals.json には、このスキルへの変更に関する回帰シナリオが含まれています。ユーザーのタスク中には読み込まれません。