- Day 49:Next.js設計 ― フォルダーの役割を決めて、変更しやすいプロジェクトを作る
- 今日のゴール
- 最初に理解したい「Next.jsの決まり」と「チームの決まり」
- 設計とは「変更する場所を予測できるようにすること」
- 各フォルダーの役割を理解する
- 今回採用するプロジェクト構造
- 実装前に依存関係を決める
- 実践:Day 48のブログを整理する
- 古いファイルを残したままにしない
- 実装後に動作確認する
- libとutilsの違いを、もう一度整理する
- typesへ集めすぎないことも大切です
- サーバーとクライアントの境界も設計に含める
- appの近くに部品を置く設計も選べます
- 規模が大きくなったら「機能別構成」も検討する
- 設計で起こりやすい失敗
- 自分で構造を設計するときの手順
- 練習問題
- Day 49のチェックリスト
- まとめ
Day 49:Next.js設計 ― フォルダーの役割を決めて、変更しやすいプロジェクトを作る
Day 49では、Day 48で作ったブログサイトを題材に、プロジェクト構造を自分で設計する方法を学びます。今回は機能を増やすのではなく、記事一覧、記事詳細、カテゴリー、検索のコードを整理し、「どこを変更すればよいか分かる構造」に整えます。
大切なのは、フォルダーをたくさん作ることではありません。それぞれのファイルが何を担当し、どのファイルを読み込んでよいかを決めることです。
今日のゴール
学習後は、次のような判断ができる状態を目指します。
- URLに対応するページを、どこへ置くか判断できます。
- 画面の部品と、データを扱う処理を分けられます。
libとutilsの使い分けを、自分の言葉で説明できます。- 共通の型を、必要なファイルから参照できます。
- サーバー専用処理を、Client Componentから誤って読み込まない構造にできます。
- 現在の規模に合った構造を選び、過剰に細分化しない設計ができます。
今回は、App Router、TypeScript、srcディレクトリを使用しているプロジェクトを前提にします。Day 48のRootLayout、トップページ、404画面、CSSは基本的にそのまま利用します。
最初に理解したい「Next.jsの決まり」と「チームの決まり」
ここは、プロジェクト設計で最も重要な前提です。
今回学ぶ6つのフォルダーが、すべてNext.jsの必須フォルダーというわけではありません。
appや、その中のpage.tsx、layout.tsx、route.tsなどにはNext.jsの規約があります。一方、components、lib、services、types、utilsという名前は、役割を整理するための慣習であり、必須の構成ではありません。Next.jsは、ルーティングの規約以外について、複数の整理方法を認めています。(🔗 nextjs.org)
| フォルダー | 今回決める役割 | Next.jsでの特別な意味 |
|---|---|---|
app | URLの入口とページ構成 | App Routerの規約があります |
components | 画面を構成する部品 | 名前自体に特別な意味はありません |
lib | アプリ固有の共通処理や外部ライブラリの設定 | 名前自体に特別な意味はありません |
services | データ取得や更新の窓口 | 名前自体に特別な意味はありません |
types | 複数箇所で共有する型 | 名前自体に特別な意味はありません |
utils | 特定の機能に依存しない小さな処理 | 名前自体に特別な意味はありません |
この表は、唯一の正解ではありません。今回のブログでは、この意味で統一するという設計方針です。
たとえば、データ取得をlibへ置くプロジェクトもあります。それ自体は間違いではありません。問題になるのは、同じプロジェクトの中で配置基準が曖昧になり、同じ種類の処理があちこちへ分散することです。
設計とは「変更する場所を予測できるようにすること」
ブログサイトへ、次の変更依頼が来たとします。
- 記事カードの余白を変えたい。
- 検索を大文字・小文字だけでなく、全角・半角にも対応させたい。
- 記事データを配列から外部CMSへ変更したい。
- 記事に著者名を追加したい。
設計が整理されていれば、おおよそ次の場所を確認できます。
| 変更内容 | 最初に確認する場所 |
|---|---|
| 記事カードの表示 | components/blog/PostCard.tsx |
| 検索文字列の正規化 | utils/text.ts |
| 記事データの取得元 | services/post.service.ts |
| 記事データの構造 | types/post.ts |
「どこかに書いてあるはず」と探し回るのではなく、役割から編集場所を推測できることが、構造を設計する価値です。
各フォルダーの役割を理解する
appはURLと画面をつなぐ場所です
appでは、URLに対応するページや、レイアウト、ローディング、エラー画面、APIの入口などを定義します。(🔗 nextjs.org)
app/
├── blog/
│ ├── [slug]/
│ │ └── page.tsx
│ ├── loading.tsx
│ └── page.tsx
├── layout.tsx
└── not-found.tsx
今回の方針では、ページは次の仕事を担当します。
- URLの値を受け取ります。
- 必要なデータ取得処理を呼び出します。
- 記事がなければ
notFound()を呼びます。 - 取得したデータを画面部品へ渡します。
ただし、「page.tsxには一切処理を書いてはいけない」という意味ではありません。小さな処理まで無理に別ファイルへ移すと、かえって読みにくくなります。
componentsは画面の部品を置く場所です
今回は、記事カードと検索フォームを置きます。
components/
└── blog/
├── PostCard.tsx
└── SearchForm.tsx
components/blogとするのは、ブログ機能に関係する部品だと分かるようにするためです。
ここで重要なのは、componentsに置いたからClient Componentになるわけではないことです。Client Componentの境界は、フォルダー名ではなく、"use client"とモジュールの依存関係で決まります。(🔗 nextjs.org)
libはアプリ固有の共通処理を置く場所です
今回のlibには、ブログ用の検索条件の整形、ブログURLの作成、カテゴリー名の取得などを置きます。
lib/
└── blog.ts
これらは「ブログという機能を知っている処理」です。
たとえば、/blog?category=reactというURLを作る関数は、汎用的な文字列操作ではありません。ブログのURL構造を知っているため、今回はlibへ置きます。
実際の開発では、認証ライブラリやデータベース接続の初期化をlibに置く設計もあります。その場合も、libが何でも置き場にならないよう、ファイル名と責務を明確にします。
servicesはデータ操作の窓口です
今回のservicesは、記事を探す、一覧を取得する、といった操作を担当します。
services/
└── post.service.ts
ページは「記事がどこに保存されているか」を直接意識せず、getPosts()やgetPostBySlug()を呼びます。
ただし、取得元を変更しても必ずサービスだけの変更で済む、という保証はありません。データ形式や認証要件が変われば、ほかの部分にも修正が必要です。サービスを置く目的は、取得元に関する知識を、できるだけ集めることです。
typesは共有するデータの形を置く場所です
types/
└── post.ts
記事の型をページ、カード、サービスで共有すれば、「同じ記事なのにファイルごとに定義が違う」という状態を避けられます。
ただし、あるボタンの中でしか使わないPropsまで、すべてtypesへ移す必要はありません。その部品だけの型は、部品の近くへ置いたほうが分かりやすい場合があります。
utilsは小さく汎用的な処理を置く場所です
utils/
└── text.ts
今回のutilsには、検索用の文字列を整える関数を置きます。
「文字列の前後の空白を消す」「比較用に小文字へ変換する」といった処理は、ブログ以外の商品検索やユーザー検索でも利用できます。
一方、getPublishedPosts()のように記事の意味を知っている関数は、今回のutilsには置きません。
今回採用するプロジェクト構造
Day 48のブログを、次のように整理します。
src/
├── app/
│ ├── blog/
│ │ ├── [slug]/
│ │ │ └── page.tsx
│ │ └── page.tsx
│ ├── globals.css
│ ├── layout.tsx
│ ├── not-found.tsx
│ └── page.tsx
├── components/
│ └── blog/
│ ├── PostCard.tsx
│ └── SearchForm.tsx
├── data/
│ ├── categories.ts
│ └── posts.ts
├── lib/
│ └── blog.ts
├── services/
│ └── post.service.ts
├── types/
│ └── post.ts
└── utils/
└── text.ts
dataは今回の追加フォルダーです。ローカルの記事データを保存するために使います。将来、外部CMSへ完全移行すれば、不要になる可能性があります。
実装前に依存関係を決める
フォルダー構成と同じくらい大切なのが、どのファイルがどのファイルを読み込むかです。
今回の基本方針は、次のようになります。
appのページ
├── components
├── services
└── lib
services
├── data
├── types
└── utils
components
├── types
└── lib
lib
├── data/categories
├── types
└── utils
utils
└── 特定のページや記事データには依存しない
types
└── 今回はほかのアプリ内ファイルに依存しない
これはフォルダーによって自動的に強制されるルールではありません。コードを書くときに守る設計方針です。
特に、次のような逆向きの依存は避けます。
// 避けたい例です。
// データ取得処理が、画面部品を読み込んでしまっています
import PostCard from "../components/blog/PostCard";
記事を取得する処理は、記事をどう表示するかまで知る必要がありません。
実践:Day 48のブログを整理する
ここから、実際にファイルを作り替えます。
今回は構造を追いやすくするため、記事データは3件の学習用データを掲載します。Day 48の6件を残したい場合は、同じ型に合わせて、そのままデータを引き継げます。
共有する型を定義する
src/types/post.ts
// ブログで利用できるカテゴリーの識別子です
export type CategorySlug = "react" | "nextjs" | "typescript";
// カテゴリー1件分の型です
export type Category = {
slug: CategorySlug;
name: string;
};
// 記事1件分の型です
export type Post = {
slug: string;
title: string;
description: string;
category: CategorySlug;
publishedAt: string;
body: string[];
};
// アプリ内で使用する検索条件です
export type BlogFilters = {
keyword: string;
category: CategorySlug | "";
};TypeScriptここには、画面表示やデータ取得の処理を書いていません。
「記事にはどの項目があるか」「検索条件はどのような形か」という契約だけを定義しています。
カテゴリーデータを分離する
src/data/categories.ts
// 値ではなく型だけを読み込みます
import type { Category } from "../types/post";
// 選択肢などで共有するカテゴリー一覧です
export const categories: readonly Category[] = [
{ slug: "react", name: "React" },
{ slug: "nextjs", name: "Next.js" },
{ slug: "typescript", name: "TypeScript" },
];TypeScriptカテゴリーを記事データから分けたのは、検索フォームが記事本文すべてを読み込まずに、カテゴリーだけ参照できるようにするためです。
今回のreadonlyは、TypeScript上で配列を書き換えないことを示します。実行時に自動でデータを凍結する機能ではありません。
記事データを配置する
src/data/posts.ts
// 記事の型を共有ファイルから読み込みます
import type { Post } from "../types/post";
// ローカルで管理する学習用の記事データです
export const posts: readonly Post[] = [
{
slug: "react-basics",
title: "Reactの基本を学ぶ",
description: "コンポーネントとJSXの考え方を整理します。",
category: "react",
publishedAt: "2026-10-01",
body: [
"Reactでは、画面をコンポーネントという部品に分けて考えます。",
"部品ごとの役割を明確にすると、画面を変更しやすくなります。",
],
},
{
slug: "nextjs-routing",
title: "Next.jsのルーティング入門",
description: "フォルダーとURLの対応関係を学びます。",
category: "nextjs",
publishedAt: "2026-10-05",
body: [
"App Routerでは、フォルダー構成でURLを定義します。",
"動的ルートを使うと、記事ごとの詳細ページを作れます。",
],
},
{
slug: "typescript-types",
title: "TypeScriptの型の基本",
description: "データの形を定義して、コードを整理します。",
category: "typescript",
publishedAt: "2026-10-09",
body: [
"型を共有すると、複数のファイルで同じデータ構造を扱えます。",
"ただし、型定義だけで外部データの実行時検証はできません。",
],
},
];TypeScriptPostの型をこのファイルで再定義せず、types/post.tsから読み込んでいる点が重要です。
汎用的な文字列処理を作る
src/utils/text.ts
// 文字列を検索で比較しやすい形へ整えます
export function normalizeSearchText(value: string): string {
return value
// 全角英数字などの表記差を一部吸収します
.normalize("NFKC")
// 前後の空白を取り除きます
.trim()
// 大文字・小文字の違いをなくします
.toLowerCase();
}TypeScriptこの関数は、記事、カテゴリー、URLを知りません。文字列だけを受け取り、文字列を返します。
そのため、ブログ以外にも利用できます。
ただし、NFKCは、ひらがなとカタカナの統一や表記揺れすべてを解決するものではありません。今回の仕様では、全角英数字などの差を一部吸収する目的で使用します。
ブログ固有の共通処理をまとめる
src/lib/blog.ts
// カテゴリーデータと共有する型を読み込みます
import { categories } from "../data/categories";
import type {
BlogFilters,
CategorySlug,
} from "../types/post";
// キーワードの最大文字数です
export const MAX_KEYWORD_LENGTH = 100;
// URLから渡される可能性がある値の型です
export type QueryValue = string | string[] | undefined;
// 同じパラメータが複数ある場合は最初の値を採用します
function getFirstValue(value: QueryValue): string {
return Array.isArray(value) ? value[0] ?? "" : value ?? "";
}
// URLの値を、アプリで使う検索条件へ変換します
export function parseBlogFilters(
rawKeyword: QueryValue,
rawCategory: QueryValue,
): BlogFilters {
const keyword = getFirstValue(rawKeyword)
.trim()
.slice(0, MAX_KEYWORD_LENGTH);
const categoryValue = getFirstValue(rawCategory);
// 定義済みのカテゴリーだけを採用します
const category = categories.find(
(item) => item.slug === categoryValue,
);
return {
keyword,
category: category?.slug ?? "",
};
}
// カテゴリーの表示名を取得します
export function getCategoryName(slug: CategorySlug): string {
return (
categories.find((category) => category.slug === slug)?.name ??
slug
);
}
// 検索条件からブログ一覧のURLを作ります
export function buildBlogUrl({
keyword = "",
category = "",
}: Partial<BlogFilters> = {}): string {
const params = new URLSearchParams();
if (keyword !== "") {
params.set("keyword", keyword);
}
if (category !== "") {
params.set("category", category);
}
const query = params.toString();
// 条件がない場合は、末尾に?を付けません
return query ? `/blog?${query}` : "/blog";
}TypeScriptこのファイルがutilsではなくlibにあるのは、カテゴリー一覧や/blogというURLなど、ブログの仕様に依存しているからです。
getFirstValue()は、このファイルでしか使わないため、外へ公開していません。すべての関数をexportする必要はありません。
データ取得の窓口を作る
今回の記事サービスは、サーバー側から呼ぶものとして設計します。
まず、サーバー専用であることを明示するためのパッケージを追加します。
# サーバー専用モジュールを明示するために追加します
npm install server-only
src/services/post.service.ts
// Client Component側からの誤った読み込みを防ぎます
import "server-only";
// データ、型、汎用処理を読み込みます
import { posts } from "../data/posts";
import type { BlogFilters, Post } from "../types/post";
import { normalizeSearchText } from "../utils/text";
// 条件に一致する記事一覧を取得します
export async function getPosts(
filters: BlogFilters,
): Promise<Post[]> {
const keyword = normalizeSearchText(filters.keyword);
// filterで新しい配列を作ってから並べ替えます
return posts
.filter((post) => {
const targetText = normalizeSearchText(
`${post.title} ${post.description}`,
);
const matchesKeyword =
keyword === "" || targetText.includes(keyword);
const matchesCategory =
filters.category === "" ||
post.category === filters.category;
return matchesKeyword && matchesCategory;
})
.sort((a, b) =>
// YYYY-MM-DD形式の日付を新しい順に並べます
b.publishedAt.localeCompare(a.publishedAt),
);
}
// slugに対応する記事を取得します
export async function getPostBySlug(
slug: string,
): Promise<Post | undefined> {
return posts.find((post) => post.slug === slug);
}TypeScriptserver-onlyを読み込んだモジュールをClient Componentからimportすると、Next.jsがビルド時のエラーとして検出できます。単にservicesという名前のフォルダーへ入れるだけでは、サーバー専用にはなりません。(🔗 nextjs.org)
なお、今回は配列処理だけなので、技術的にはasyncは必須ではありません。将来、取得元を非同期のデータベースやCMSへ変更することを想定し、呼び出し側が最初からawaitする契約にしています。
サービス内でnotFound()を呼ばない理由
今回は、記事がなければundefinedを返します。
// 見つからない場合はundefinedを返します
return posts.find((post) => post.slug === slug);TypeScript記事がないときに404画面へ切り替えるか、別の表示をするかは、ページ側で決めます。
サービスが直接notFound()を呼ぶ設計もありますが、今回はサービスをページ以外からも使いやすくするため、データの取得と画面の判断を分けています。
記事カードを移動してimportを変更する
Day 48のPostCard.tsxをcomponents/blogへ移動します。
src/components/blog/PostCard.tsx
// リンク、型、ブログ用の共通処理を読み込みます
import Link from "next/link";
import type { Post } from "../../types/post";
import {
buildBlogUrl,
getCategoryName,
} from "../../lib/blog";
// この型は、この部品だけで使うため同じファイルに置きます
type PostCardProps = {
post: Post;
};
// 記事1件分を表示します
export default function PostCard({ post }: PostCardProps) {
return (
<article className="post-card">
<div className="post-meta">
<Link
className="category-badge"
href={buildBlogUrl({ category: post.category })}
>
{getCategoryName(post.category)}
</Link>
<time dateTime={post.publishedAt}>
{post.publishedAt}
</time>
</div>
<h2>
<Link href={`/blog/${post.slug}`}>
{post.title}
</Link>
</h2>
<p>{post.description}</p>
</article>
);
}TSX記事カードは、サービスを呼んでいません。親から受け取った記事を表示しています。
この設計なら、通常の記事一覧、関連記事、おすすめ記事などで同じ部品を使いやすくなります。
検索フォームも機能別フォルダーへ移動する
src/components/blog/SearchForm.tsx
// カテゴリー、型、ブログ用の定数を読み込みます
import { categories } from "../../data/categories";
import type { BlogFilters } from "../../types/post";
import { MAX_KEYWORD_LENGTH } from "../../lib/blog";
// 通常のGETフォームなので"use client"は不要です
export default function SearchForm({
keyword,
category,
}: BlogFilters) {
return (
<form
className="search-form"
action="/blog"
method="get"
role="search"
>
<div className="form-field">
<label htmlFor="keyword">キーワード</label>
<input
id="keyword"
name="keyword"
type="search"
defaultValue={keyword}
maxLength={MAX_KEYWORD_LENGTH}
placeholder="例:React"
/>
</div>
<div className="form-field">
<label htmlFor="category">カテゴリー</label>
<select
id="category"
name="category"
defaultValue={category}
>
<option value="">すべて</option>
{categories.map((item) => (
<option key={item.slug} value={item.slug}>
{item.name}
</option>
))}
</select>
</div>
{/* 入力値をクエリ文字列として送信します */}
<button className="button" type="submit">
検索する
</button>
</form>
);
}TSXここでも記事サービスは読み込んでいません。フォームが必要としているのは、カテゴリーと検索条件だけです。
一覧ページを「組み立てる場所」にする
src/app/blog/page.tsx
// Metadataと表示部品を読み込みます
import type { Metadata } from "next";
import Link from "next/link";
import PostCard from "../../components/blog/PostCard";
import SearchForm from "../../components/blog/SearchForm";
// URLの処理と記事サービスを読み込みます
import {
getCategoryName,
parseBlogFilters,
type QueryValue,
} from "../../lib/blog";
import { getPosts } from "../../services/post.service";
// 一覧ページのMetadataです
export const metadata: Metadata = {
title: "記事一覧",
description:
"React、Next.js、TypeScriptの記事を検索できます。",
};
// ページだけで使うPropsなので、このファイルに置きます
type BlogPageProps = {
searchParams: Promise<{
keyword?: QueryValue;
category?: QueryValue;
}>;
};
// URL、データ、表示部品をつなぐページです
export default async function BlogPage({
searchParams,
}: BlogPageProps) {
const query = await searchParams;
// URLの値をアプリ内の条件へ変換します
const filters = parseBlogFilters(
query.keyword,
query.category,
);
// データの取得元はサービスに任せます
const posts = await getPosts(filters);
return (
<section>
<header className="page-heading">
<h1>記事一覧</h1>
<p>カテゴリーとキーワードで記事を探せます。</p>
</header>
{/* URLの条件変更に合わせて初期値を更新します */}
<SearchForm
key={JSON.stringify(filters)}
{...filters}
/>
<div className="results-summary">
<p>キーワード:{filters.keyword || "指定なし"}</p>
<p>
カテゴリー:
{filters.category
? getCategoryName(filters.category)
: "すべて"}
</p>
<p>{posts.length}件の記事があります。</p>
<Link href="/blog">条件を解除する</Link>
</div>
{posts.length === 0 ? (
<p>該当する記事はありません。</p>
) : (
<ul className="post-list">
{posts.map((post) => (
<li key={post.slug}>
<PostCard post={post} />
</li>
))}
</ul>
)}
</section>
);
}TSX現在のApp Routerでは、ページのsearchParamsはPromiseとして受け取り、awaitで値を取り出します。また、同じキーが複数指定された場合は配列になるため、今回もそれを考慮しています。(🔗 nextjs.org)
ページを読むだけで、「条件を読む」「記事を取得する」「部品で表示する」という流れが分かるようになりました。
詳細ページもサービス経由にする
src/app/blog/[slug]/page.tsx
// Metadata、リンク、404処理を読み込みます
import type { Metadata } from "next";
import Link from "next/link";
import { notFound } from "next/navigation";
// 記事サービスとブログ用の共通処理を読み込みます
import {
getPostBySlug,
getPosts,
} from "../../../services/post.service";
import {
buildBlogUrl,
getCategoryName,
} from "../../../lib/blog";
// このページで使うPropsです
type BlogDetailPageProps = {
params: Promise<{
slug: string;
}>;
};
// ビルド時に用意する記事のslugを取得します
export async function generateStaticParams() {
const posts = await getPosts({
keyword: "",
category: "",
});
return posts.map((post) => ({
slug: post.slug,
}));
}
// 記事に合わせたMetadataを生成します
export async function generateMetadata({
params,
}: BlogDetailPageProps): Promise<Metadata> {
const { slug } = await params;
const post = await getPostBySlug(slug);
if (!post) {
notFound();
}
return {
title: post.title,
description: post.description,
};
}
// 記事詳細を表示します
export default async function BlogDetailPage({
params,
}: BlogDetailPageProps) {
const { slug } = await params;
const post = await getPostBySlug(slug);
// 画面としての404判断はページ側で行います
if (!post) {
notFound();
}
return (
<article className="article-detail">
<p>
<Link href="/blog">← 記事一覧へ</Link>
</p>
<header className="article-header">
<Link
className="category-badge"
href={buildBlogUrl({ category: post.category })}
>
{getCategoryName(post.category)}
</Link>
<h1>{post.title}</h1>
<time dateTime={post.publishedAt}>
公開日:{post.publishedAt}
</time>
<p>{post.description}</p>
</header>
<div className="article-body">
{post.body.map((paragraph, index) => (
// 今回の段落は固定順なのでindexを利用します
<p key={`${post.slug}-${index}`}>
{paragraph}
</p>
))}
</div>
</article>
);
}TSX動的ルートのparamsもPromiseとして受け取っています。(🔗 nextjs.org)
今回、Metadata生成と本文表示で記事取得関数をそれぞれ呼んでいます。ローカル配列では小さな処理ですが、将来データベースへ変更する場合は、「サービス関数にしただけで重複取得がなくなる」と考えず、実際の取得回数やキャッシュも確認します。
古いファイルを残したままにしない
移行が完了したら、Day 48で使っていた次のファイルを確認します。
- 旧
src/components/PostCard.tsxは、新しい場所へ移動済みなら削除します。 - 旧
src/components/SearchForm.tsxも、移動済みなら削除します。 - 旧
src/lib/blog.tsにあった記事取得・検索処理は、今回の内容へ置き換えます。 data/posts.ts内に以前の型定義が残っていれば、共有型のimportへ統一します。
新旧のファイルが両方あると、修正したつもりでも別のファイルを読み込んでいる、という混乱が起こりやすくなります。
実装後に動作確認する
今回は、掲載した3件のデータを使用した場合、次の結果になります。
| 操作・URL | 期待する結果 |
|---|---|
/blog | 3件表示されます |
/blog?category=react | Reactの記事が1件表示されます |
/blog?keyword=React | Reactの記事が1件表示されます |
/blog?keyword=React | 全角英字でもReactの記事が1件表示されます |
/blog?keyword=React&category=nextjs | 0件と表示されます |
/blog/react-basics | 記事詳細が表示されます |
/blog/not-exist | 見つからない画面になります |
開発サーバーで確認した後、本番ビルドも行います。
# 型の整合性を確認します
npx tsc --noEmit
# 本番用にビルドします
npm run build
# ビルド成功後に本番用サーバーを起動します
npm run start
Day 48のデータを引き継いだ場合は、記事件数などの期待値を、そのデータに合わせて調整します。
libとutilsの違いを、もう一度整理する
この2つには、世界共通の厳密な境界があるわけではありません。今回の判断基準は、特定の機能を知っているかどうかです。
| 処理 | 今回の配置 | 判断理由 |
|---|---|---|
| 検索用に文字列を小文字化する | utils/text.ts | ブログ以外でも使えます |
/blogの検索URLを作る | lib/blog.ts | ブログのURLを知っています |
| カテゴリーslugから表示名を探す | lib/blog.ts | ブログのカテゴリーを知っています |
| 記事一覧を取得する | services/post.service.ts | データ操作の入口です |
| 記事カードを表示する | components/blog/PostCard.tsx | 画面の部品です |
迷った場合は、「別のアプリへそのまま持っていっても意味が通るか」を考えると整理しやすくなります。
ただし、将来使うかもしれないという理由だけで、過度に汎用化する必要はありません。まずは具体的な処理として書き、実際に共通点が見えたところで切り出します。
typesへ集めすぎないことも大切です
今回、PostとBlogFiltersは共有型としてまとめました。一方、PostCardPropsやBlogPagePropsは、それぞれのファイルへ置きました。
判断基準は次の通りです。
- 複数の場所で同じ意味として共有する型は、
typesへ置きます。 - 特定の部品やページだけで使う型は、その近くへ置きます。
- 型を探すためだけに多くのファイルを開く必要があるなら、分割しすぎていないか見直します。
また、型のためだけの依存はimport typeで表現すると、値を読み込むimportとの違いが明確になります。
// 型だけが必要なことを明示します
import type { Post } from "../types/post";TypeScriptサーバーとクライアントの境界も設計に含める
フォルダー名だけでは秘密情報を守れません
servicesやlibという名前は、セキュリティ機能ではありません。
今回のサービスにはserver-onlyを追加しましたが、これは誤importを防ぐための仕組みです。認証・認可を自動で行うものではありません。(🔗 nextjs.org)
"use client"を上位へ付けすぎない
Client Componentの入口からimportしたモジュールは、クライアント側の依存関係へ入ります。したがって、ページ全体を何となくClient Componentにしてからサーバー専用サービスを読み込むのではなく、操作が必要な部品だけをClient Componentに分けます。(🔗 nextjs.org)
今回のGETフォームにはStateやイベントハンドラーがないため、Client Componentへ変更する必要はありません。
環境変数の配置と公開範囲を区別する
APIキーなどを使う場合、.env.localは通常、srcの中ではなく、package.jsonと同じプロジェクトルートへ置きます。
また、NEXT_PUBLIC_が付いた環境変数はブラウザーへ公開される前提の値です。秘密鍵や非公開トークンへ、この接頭辞を付けないでください。(🔗 nextjs.org)
公開する値は必要な項目に絞る
将来、記事データに管理用メモや未公開情報が加わっても、画面やAPIへそのまま全項目を渡す設計にはしません。
サービス側で取得できる情報と、利用者へ公開してよい情報は別です。必要になった段階で、一覧用のデータ型や公開用の返却形式を分けます。
appの近くに部品を置く設計も選べます
今回は、分かりやすさを優先してcomponentsをappの外へ置きました。しかし、ブログでしか使わない部品を、ブログのルートに近づける方法もあります。
src/
└── app/
└── blog/
├── _components/
│ ├── PostCard.tsx
│ └── SearchForm.tsx
├── [slug]/
│ └── page.tsx
└── page.tsx
Next.jsでは、app内へ関連ファイルを一緒に置くことができます。また、_componentsのように先頭へ_を付けたフォルダーは、プライベートフォルダーとしてルーティングから除外されます。(🔗 nextjs.org)
ここでいう「プライベート」は、ルーティング上の扱いです。秘密情報の保護やアクセス制限を意味するものではありません。
今回は次のように判断します。
- 複数の機能から使う表示部品は、
src/componentsへ置きます。 - そのページ周辺だけで使う部品は、
app内への配置も検討します。 - 同じ部品を両方へコピーして管理しないようにします。
規模が大きくなったら「機能別構成」も検討する
今回の構成は、役割ごとに分けるレイヤー別構成に近い形です。
記事だけでなく、ユーザー、注文、決済などが増えると、それぞれのcomponents、services、typesを行き来する負担が大きくなる場合があります。そのときは、機能ごとにまとめる選択肢があります。
src/
├── app/
├── components/
│ └── ui/
├── features/
│ ├── blog/
│ │ ├── components/
│ │ ├── services/
│ │ ├── types.ts
│ │ └── query.ts
│ └── account/
│ ├── components/
│ ├── services/
│ └── types.ts
├── lib/
└── utils/
これは今回すぐに移行するための指示ではなく、将来の選択肢です。
| 構成 | 向いている状況 | 注意点 |
|---|---|---|
| 小さくまとめる構成 | 試作やごく小さなアプリ | 成長したら責務を整理します |
| 今回の役割別構成 | 役割を学びながら開発する段階 | 同じ機能のファイルが複数箇所へ分かれます |
| 機能別構成 | 独立した機能が増えた段階 | 共通処理と機能固有処理の境界を決めます |
最初から最大規模の構造を用意しないことも、設計の大切な判断です。
設計で起こりやすい失敗
| 問題 | 起こりやすい状態 | 改善の方向 |
|---|---|---|
page.tsxが巨大になる | データ取得、検索、表示が混在します | 役割が異なる処理から切り出します |
utilsが何でも置き場になる | 記事取得や認証まで入ります | データ操作や機能固有処理を分けます |
| 型が重複する | ファイルごとにPostを定義します | 共有する型を統一します |
| 小さなファイルが増えすぎる | 数行ごとに無条件で分割します | 一緒に変更する処理を近づけます |
| 新旧ファイルが併存する | どちらが使われているか不明になります | importを確認して古い方を削除します |
| 依存関係が循環する | AがBを読み、BがAを読みます | 共通部分を下位のモジュールへ移します |
| サーバー処理を誤importする | フォルダー名だけで安全だと思います | 境界を明示し、依存関係を確認します |
循環依存を避ける
たとえば、次の関係は避けたい状態です。
post.service.ts
→ lib/blog.ts
→ post.service.ts
今回、ブログURLの作成処理と記事データの取得処理を分けたのは、必要以上に互いを参照しない構造にするためでもあります。
共通の型が必要なら、双方がtypes/post.tsを参照します。
自分で構造を設計するときの手順
実際に新しいプロジェクトを設計する場合は、先にフォルダー名を並べるのではなく、次の順番で考えます。
- 作る画面とURLを書き出します。
- 扱うデータの種類を書き出します。
- 利用者の操作と、サーバーで行う処理を分けます。
- 画面、データ操作、共通処理の役割を決めます。
- どのファイルからどのファイルを読み込むか決めます。
- 現在必要なフォルダーだけを作ります。
- 機能が増えた時点で、分割方法を見直します。
設計メモのテンプレート
新しいアプリを作るときは、次のような短いメモを残すだけでも効果があります。
プロジェクト:学習用ブログ
【画面】
・/:トップページ
・/blog:記事一覧と検索
・/blog/[slug]:記事詳細
【データ】
・記事
・カテゴリー
【配置ルール】
・app:URLの入口とページ構成
・components:表示部品
・services:サーバー側の記事取得
・types:共有するデータの型
・lib:ブログ固有の共通処理
・utils:汎用的な小さな処理
【依存のルール】
・ページはサービスを呼び出す
・記事カードは記事サービスを呼ばない
・サービスは画面部品を読み込まない
・utilsは記事データを読み込まない
【今回やらないこと】
・記事投稿機能
・ログイン
・データベース保存
このメモにより、必要な設計と、まだ必要のない設計を区別できます。
練習問題
記事カードへ著者名を追加する
記事へauthorNameを追加して、一覧と詳細に表示します。
- 共有する記事の型を変更します。
- 記事データを更新します。
- 必要な画面へ表示を追加します。
- 型エラーが、変更漏れの発見にどう役立つか確認します。
おすすめ記事の取得処理を追加する
getRecommendedPosts()という関数を、記事サービスへ追加します。
最初は「新しい記事を2件返す」という簡単な仕様で構いません。トップページから呼び出し、既存のPostCardで表示します。
この練習では、取得方法と表示方法が分かれている利点を確認できます。
検索条件へ並び順を追加する
sortという条件を追加して、新しい順と古い順を切り替えます。
型、URL処理、サービス、フォームのどこを変更する必要があるか、実装前に書き出してください。
すべてを1ファイルへ集めることが目的ではありません。それぞれの責務に応じて、変更箇所を予測できるかが確認ポイントです。
Day 49のチェックリスト
appの規約と、任意のフォルダー構成を区別できます。componentsを表示部品の置き場として整理できます。servicesへデータ操作の窓口をまとめられます。typesへ共有型を置き、部品専用の型は近くに置けます。libとutilsの配置基準を説明できます。- フォルダー名だけではServer/Clientの境界にならないと理解しています。
- ファイル移動後にimportと古いファイルを確認できます。
- 機能を変えずに構造を整理し、動作確認できます。
- 必要以上に抽象化・細分化しない判断ができます。
まとめ
Day 49では、ブログサイトを題材に、app、components、lib、services、types、utilsの役割を決めました。
今回の設計では、ページは処理をつなぎ、サービスはデータを扱い、コンポーネントは表示し、型は共通の契約を表すという分担にしています。libにはブログ固有の共通処理を、utilsには汎用的な処理を置きました。
よい構造は、フォルダーの数では決まりません。変更したい内容に対して、編集する場所が予測でき、影響範囲を確認しやすいことが重要です。まずは今回の構造で小さな変更を重ね、自分で配置の理由を説明できる状態を目指します。
