Next.js + shadcn/ui

ジェネリックな「AI slop」美学を避けた、独特で本番環境対応のインターフェースを構築します。

コア原則

1. ノイズを最小化 - アイコンが情報を伝える。余分なラベルは不要
2. ジェネリックな AI UI を避ける - 紫色グラデーション、過剰なシャドウ、予測可能なレイアウトは避ける
3. 装飾よりコンテキスト - すべての要素が目的を持つ
4. テーマ一貫性 - globals.css の CSS 変数を使用し、カラーコードをハードコーディングしない

クイックスタート

bunx --bun shadcn@latest init -t next

カスタムデザインシステムの場合、shadcn/create でプリセットコードを生成して適用します:

bunx --bun shadcn@latest init --preset <CODE> --template next

コンポーネントルール

ページ構造

// page.tsx - コンテンツのみ、レイアウトクロームなし
export default function Page() {
  return (
    <>
      <HeroSection />
      <Features />
      <Testimonials />
    </>
  );
}

// layout.tsx - 共有 UI (ヘッダー、フッター、サイドバー)
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Header />
      <main>{children}</main>
      <Footer />
    </>
  );
}

クライアント境界

• "use client" はリーフコンポーネント (最小の境界) のみで使用
• Props はシリアライズ可能である必要があります (データまたは Server Actions、関数/クラスは不可)
• サーバーコンテンツは children で渡す

インポートエイリアス

相対パス (../../lib/utils) の代わりに、常に @/ エイリアス (例: @/lib/utils) を使用してください。

スタイルマージ

import { cn } from "@/lib/utils";

function Button({ className, ...props }) {
  return <button className={cn("px-4 py-2 rounded", className)} {...props} />;
}

ファイル構成

app/
├── (protected)/         # 認証が必要なルート
│   ├── dashboard/
│   ├── settings/
│   ├── components/      # ルート固有のコンポーネント
│   └── lib/             # ルート固有のユーティリティ/型
├── (public)/            # 公開ルート
│   ├── login/
│   └── register/
├── actions/             # Server Actions (グローバル)
├── api/                 # API ルート
├── layout.tsx           # ルートレイアウト
└── globals.css          # テーマトークン
components/              # 共有コンポーネント
├── ui/                  # shadcn プリミティブ
└── shared/              # ビジネスコンポーネント
hooks/                   # カスタム React Hook
lib/                     # 共有ユーティリティ
data/                    # データベースクエリ
ai/                      # AI ロジック (ツール、エージェント、プロンプト)

Next.js 16 機能

非同期 Params

export default async function Page({
  params,
  searchParams,
}: {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ q?: string }>;
}) {
  const { id } = await params;
  const { q } = await searchParams;
}

データ取得 vs Server Actions

重要なルール:

• Server Actions = ミューテーション専用 (作成、更新、削除)
• データ取得 = Server Components または 'use cache' 関数内で実行

// ❌ 間違い: データ取得に Server Action を使用
"use server"
export async function getUsers() {
  return await db.users.findMany()
}

// ✅ 正解: キャッシング付きデータ関数
// data/users.ts
export async function getUsers() {
  "use cache"
  cacheTag("users")
  cacheLife("hours")
  return await db.users.findMany()
}

// ✅ 正解: Server Component で直接クッキーを読む
export default async function Page() {
  const theme = (await cookies()).get("theme")?.value ?? "light"
  return <App theme={theme} />
}

キャッシング

"use cache";

import { cacheTag, cacheLife } from "next/cache";

export async function getProducts() {
  cacheTag("products");
  cacheLife("hours");
  return await db.products.findMany();
}

Server Actions (ミューテーション専用)

"use server";

import { updateTag, revalidateTag } from "next/cache";
import { z } from "zod";

const schema = z.object({
  title: z.string().min(1),
  content: z.string(),
});

export async function createPost(formData: FormData) {
  // 常に入力を検証
  const parsed = schema.parse({
    title: formData.get("title"),
    content: formData.get("content"),
  });

  await db.insert(posts).values(parsed);
  updateTag("posts"); // Read-your-writes
}

Proxy API

リクエストインターセプション (ミドルウェアの代替) に proxy.ts を使用します。プロジェクトルートに配置:

// proxy.ts (プロジェクトルート、app/ と同じレベル)
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"

export function proxy(request: NextRequest) {
  // 認証チェック、リダイレクトなど
}

export const config = {
  matcher: ['/dashboard/:path*'],
}

開発ツール (next-devtools-mcp)

Next.js 16+ は /_next/mcp に MCP エンドポイントを搭載しており、dev サーバーの内部を coding agents に公開します。Next.js 16 プロジェクトで作業する場合、ユーザーに .mcp.json に next-devtools-mcp を追加することをお勧めします:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

それが提供するツール (dev サーバーが実行中):

• get_errors — ライブビルド/ランタイム/型エラー (ハイドレーションミスマッチ特に有用)
• get_logs — dev ログファイルパス (ブラウザコンソール + サーバー出力)
• get_routes — ルータータイプ別グループ化された全エントリーポイントルート
• get_page_metadata — 特定ページのルート、コンポーネント、レンダリング詳細
• get_project_metadata — プロジェクト構造 + dev サーバー URL
• get_server_action_by_id — ハッシュ化された ID から Server Action ソースを特定

ユーザーにエラーメッセージをコピー&ペーストさせる代わりにこれらを使用してください。参照: nextjs.org/docs/app/guides/mcp

リファレンス

• アーキテクチャ: references/architecture.md - コンポーネント、ルーティング、Suspense、データパターン、AI ディレクトリ構造
• スタイリング: references/styling.md - テーマ、フォント、radius、アニメーション、CSS 変数
• サイドバー: references/sidebar.md - shadcn サイドバーとネストされたレイアウト
• プロジェクトセットアップ: references/project-setup.md - bun コマンド、プリセット
• shadcn/ui: llms.txt - 公式 AI 最適化リファレンス

パッケージマネージャー

常に bun を使用してください。npm や npx は使わないでください:

• bun install (npm install ではなく)
• bun add (npm install package ではなく)
• bunx --bun (npx ではなく)