mmuulan
FrontendBeginner

Next.js/React キャッチアップメモ

Created 2026-04-16 · Updated 2026-07-04

Next.js + React キャッチアップ（AIコーディング向け・15〜30分）

対象：一般的なWeb開発の経験はあるが、React / Next.js の経験は薄い方。 目的：AIにコードを書かせるとき、生成物を正しく指示・レビューできる「設計・構成・命名の勘所」を掴む。文法そのものは扱わない。 出典：断りのない箇所は Next.js 公式ドキュメント（App Router / v16系）に基づく。公式以外は都度明記する。

0. 5分でわかる全体像

Next.js は React のフレームワーク。React が「UIを部品（コンポーネント）で組む考え方」を提供し、Next.js が「ルーティング・データ取得・サーバーレンダリング・ビルド」といった実アプリに必要な骨組みを乗せる、という関係。

現在の主流は App Router（app/ ディレクトリを使う方式）で、新規プロジェクトは App Router を使うのが公式の推奨。古い記事に出てくる Pages Router（pages/）とは設計思想が違うので、AIに指示するときも記事を参考にするときも「App Router 前提か」を必ず確認する。

AIコーディングで最も効く前提知識は次の3つ。この後で順に説明する。

  1. フォルダ構成がそのままURLになる（ファイルシステムルーティング）
  2. コンポーネントはデフォルトでサーバー側で動く（Server Component）。対話が必要な部分だけクライアント側にする
  3. どこに何を置くかの「置き場所のルール」を決めておくと、AIの生成物が散らからない

1. ディレクトリ構成とルーティング

URLはフォルダで決まる

App Router では app/ の中のフォルダ構造がそのままURLになる。フォルダに page.tsx を置くと、そのフォルダが公開ルート（アクセス可能なページ）になる。

app/
├── page.tsx            → /
├── about/
│   └── page.tsx        → /about
└── blog/
    ├── page.tsx        → /blog
    └── [slug]/
        └── page.tsx    → /blog/任意の値

page.tsx があるフォルダだけがページになる。だからコンポーネントやユーティリティを同じフォルダに一緒に置いても、それらは勝手にページ化されない（コロケーション＝関連ファイルを近くに置く、が可能）。

覚えるべき特殊ファイル名

App Router には決まった名前のファイル規約がある。名前に意味があるので、AIが生成したファイルがこの規約に沿っているかを見られると良い。

  • page.tsx … そのルートの本体ページ
  • layout.tsx … 配下のページを包む共通UI（ヘッダー・ナビ・フッターなど）。各階層に置け、入れ子になる。app/ 直下のルートレイアウトは必須
  • loading.tsx … 読み込み中に自動表示されるUI（スケルトンやスピナー）
  • error.tsx … 配下でエラーが起きたときのUI（エラー境界）
  • route.ts … APIエンドポイント（GET / POST などのHTTPメソッド関数をexportする）

これらは階層構造に従って入れ子で適用される。たとえば loading.tsx や layout.tsx は、置いた階層以下にだけ効く。

フォルダ名の特殊記法

  • [slug] … 動的セグメント。/blog/123 の 123 のように、値が可変な部分。角括弧で囲む
  • (グループ名) … ルートグループ。URLには影響しない整理用のフォルダ。たとえば (auth)/login/page.tsx のURLは /login であり /auth/login にはならない。ログイン系とダッシュボード系で別レイアウトを当てたい、といった用途に使う
  • _フォルダ名 … プライベートフォルダ。アンダースコア始まりはルーティングから除外される。app/ 内にコンポーネントやユーティリティを置きたいがページ化したくないときに使う

src フォルダと置き場所の方針

Next.js は app/ を含むアプリコードを任意の src/ フォルダにまとめることも公式にサポートしている。設定ファイル類（プロジェクトルート）とアプリコードを分けられる。

公式は特定のアーキテクチャを強制しない。components・lib・hooks・utils といったフォルダ名にフレームワーク上の特別な意味はなく、「チームで一貫していればよい」というのが公式の立場。代表的な方針は2つ。

  • app/ はルーティング専用にして、共通コードは app/ の外（プロジェクトルートや src/ 直下）の共有フォルダに置く
  • 共有コードも app/ の中にまとめる

どちらでもよいが、混在させず一貫させることが最重要。AIに任せる前に「この方針で置いて」と最初に固定しておくと、生成物が散らからない。

補足（公式以外）：機能単位でフォルダを切る「feature（機能）ベース」の構成——features/billing/ の下にその機能のコンポーネント・アクション・型をまとめる——は、規模が大きくなったときに破綻しにくい実務パターンとして各所で推奨されている（出典：DEV Community "The Next.js 15 App Router Project Structure That Scales" 2026、makerkit.dev "Next.js App Router Project Structure"）。フラットに全部 components/ へ入れると50ファイルあたりで崩れる、という経験則が語られている。ただしこれらは公式規約ではなく設計上の一提案。

2. Server Component と Client Component（最重要の考え方）

App Router で最大の思考転換がここ。すべてのコンポーネントはデフォルトでServer Component（サーバー側で実行される）。対話が必要な部分だけ、'use client' を付けてClient Componentにする。

使い分けの判断

Server Component（デフォルト・何も書かない）

  • データ取得、静的な表示、SEO向けの要素
  • サーバー上で動くのでコードがブラウザに送られず、バンドルが小さくなり高速

Client Component（ファイル先頭に 'use client'）が必要なのは、次のいずれかがあるとき

  • 状態管理（useState など React のフック）
  • イベントハンドラ（onClick onChange など）
  • ブラウザAPI（window localStorage など、サーバーに存在しないもの）

ざっくり言えば「クリックしたり、入力したり、値を覚えたりする部分」だけがClient。それ以外は全部Serverでよい。

'use client' の正しい使い方

公式が明言している重要ポイント：すべてのファイルに 'use client' を付ける必要はない。この指示は「クライアントとサーバーの境界（entry point）」を宣言するもので、Server Component の中から直接呼び出したいClient Componentのファイルにだけ付ける。付けたファイルからimportされる配下も自動的にクライアント側になる。

実務上の型（公式の推奨）：

  • レイアウトやページはServerのまま保つ。ボタン1つに onClick が必要だからといってページ全体を 'use client' にしない
  • その対話部分だけを別ファイルに切り出し、そのファイルにだけ 'use client' を付ける
  • Server Componentを木の上のほうに、Client Componentをできるだけ末端（deep）に置くのが最適化のコツ。「対話が必要な小さな島（interactive islands）」を小さく保つ、というイメージ

補足（公式以外）：'use client' は「サーバーレンダリングを止める」ものではない。Client Component も初回リクエストではサーバーでHTMLに描画され、ブラウザ側でハイドレーション（JSを紐づけて対話可能にする処理）される。この誤解が多いと解説されている（出典：Strapi Blog "Mastering 'use client' in Next.js" 2026）。

境界をまたぐときの制約

Server から Client へ props を渡すとき、その props は シリアライズ可能（React がサーバー→クライアントへ送れる形式）でなければならない。たとえば関数をそのまま props で渡すことはできない。この制約はAIの生成物でもよくエラーになるポイントなので、頭の片隅に置いておく。

3. データ取得と変更（Server Actions）

読み取り

Server Component は async にして、その中で直接データを取得できる（DBやSDKを直接呼ぶ）。APIを別途作らなくても、ページのコンポーネント内でデータフェッチが完結するのが App Router の強み。

書き込み（Server Actions）

フォーム送信やデータ更新（mutation）には Server Actions を使うのが現在の主流。サーバー上で動く関数だが、Client Component から直接呼び出せる。

  • ファイルの先頭に 'use server' を付けると、そのファイルのexport関数がすべてServer Actionになる
  • Client Component から呼ぶ場合は、Server Actionを専用ファイルに切り出して 'use server' を付ける必要がある
  • Server Actionの戻り値はクライアントに送られるため、UIに必要なデータだけ返す（生のDBレコードをそのまま返さない）のが公式のセキュリティ指針

API Route（route.ts）はいつ使うか

自分のアプリ内のデータ操作は Server Actions で足りることが多い。app/api/ の API Route は、外部クライアント向けのRESTエンドポイント、Webhook受信、ファイルアップロードなど「HTTPの口が必要な場面」に絞るのが実務上の目安。

補足（公式以外）：この「自前データはServer Actions、外部連携やWebhookはAPI Route」という切り分けは実務記事で広く共有されている（出典：DEV Community "The Next.js 15 App Router Project Structure That Scales" 2026）。テスト容易性のため、ビジネスロジックはServer Actionから純粋な関数（service）へ切り出す、という設計提案もある。

4. コンポーネント設計の勘所

  • 1コンポーネント1責務。表示だけのもの、対話するものを分ける。特にServer/Clientの境界と責務の境界を揃えると見通しが良い
  • 対話の島を小さく。'use client' の範囲を最小化する。ページ全体ではなくボタン単体に付ける
  • データは上から props で流す。Server Componentでデータを取得し、必要な値だけを子のClient Componentに渡す。この一方向の流れを崩さない
  • 共通プロバイダ（テーマ等）はできるだけ木の深い位置で {children} だけを包む。<html> 全体を包まない。そうするとServer部分の静的最適化が効きやすい（公式の good to know）
  • third-party製の対話ライブラリ（カルーセル等で内部的に useState を使うもの）をServer Componentで直接使うとエラーになることがある。自前のClient Componentで包んでから使う、というのが公式の対処法

5. 命名規則の考え方

Next.js は予約されたファイル名（page layout loading error route など）以外の命名を強制しない。だからこそチームで規約を決める必要がある。AIに書かせる前に決めておきたいのは次のあたり。

  • 予約ファイル名は規約どおり正確に（layout.tsx を別名にするとルーターが認識しない、と公式が明記）
  • コンポーネントの命名（PascalCase）とファイル名の方針（kebab-case か PascalCase か）を最初に固定し、混在させない
  • 動的セグメント（[id] [slug]）の名前は、コード内で参照する params のキーになるので意味の分かる名前にする
  • ルートグループ (name) は整理用と分かる名前に（(auth) (marketing) など）

要点は「フレームワークが決めている部分は正確に守る」「決めていない部分はチームで一貫させる」の2つに尽きる。

6. AIコーディングで効くチェックリスト

AIに指示を出す前・生成物をレビューするときに、この観点を持っておくと精度が上がる。

指示する前に固定しておくこと

  • App Router 前提であることを明示する（Pages Router の古い書き方を混ぜさせない）
  • ディレクトリ方針（app/ はルーティング専用か、共有コードも入れるか。src/ を使うか）
  • 命名規則（ファイル名・コンポーネント名の形式）
  • feature単位で切るか、種類別（components/hooks/lib）で切るか

生成物をレビューするときに見ること

  • 'use client' が必要な場所にだけ付いているか（ページ全体に付けて肥大化していないか）
  • Server Component の中で状態やイベントハンドラを使おうとしていないか（それはエラーになる）
  • Server→Clientのpropsにシリアライズできないもの（関数など）を渡していないか
  • 予約ファイル名が正確か（layout page などのスペル・配置）
  • データ取得はServer側で完結しているか、無駄にAPI Routeを作っていないか
  • 秘密情報（APIキー等）をクライアントに露出していないか（NEXT_PUBLIC_ を付けた環境変数はブラウザに見える、という公式注意点。Vercel Academy でも強調）

AIに渡すと精度が上がる情報

  • 「App Router / Next.js 16系 / TypeScript」といったバージョンと前提
  • 既存のディレクトリツリー（どこに置くかを迷わせない）
  • Server/Client のどちらで動かしたいか（対話が必要かどうか）

まとめ（1分で振り返り）

  1. フォルダ＝URL。page.tsx があるフォルダがページ。layout / loading / error / route は予約名
  2. デフォルトはServer。状態・イベント・ブラウザAPIが要る部分だけ 'use client' を最小範囲で付ける
  3. データはServerで取得し、propsで下へ。更新はServer Actions、外部連携はAPI Route
  4. 公式が強制しない部分（構成・命名）はチームで一貫させ、AIにも最初に固定して渡す

この4点を押さえておけば、AIが生成したNext.jsコードの良し悪しを判断し、的確に指示を出し直せるようになる。