Next.jsで学ぶReact講座 90日コース | React実践力を身につける - Day 32:React設計演習

React Next.jsで学ぶReact講座90日コース
スポンサーリンク
スポンサーリンク

Day 32:既存アプリを役割ごとに整理する

アプリの機能が増えると、画面、状態管理、データ保存、補助処理がひとつのファイルに集まり、修正しにくくなります。この日は、Day 25のタスク管理アプリを題材に、コードをcomponents、hooks、services、utils、typesへ分けます。

それぞれの役割は、次のように考えます。

  • components:画面に表示する部品です。
  • hooks:ReactのStateやEffectを使う、再利用可能な処理です。
  • services:LocalStorageやAPIなど、アプリの外部とのやり取りを担当します。
  • utils:Reactに依存しない、入力値の加工や絞り込みなどの関数です。
  • types:TypeScriptで使うデータの型を定義します。

これは一例で、すべてのアプリに同じフォルダー構成を当てはめる必要はありません。大切なのは、コードを読む人が「この処理はどこにあるか」を予測できることです。

1. まず既存コードの役割を見つける

Day 25のタスクアプリには、タスクの追加、完了切り替え、一覧表示、検索、保存などの処理がありました。まず各処理がどの役割に当たるか分類します。

  • タスクフォーム、一覧、タスク行は画面部品なので`components`です。
  • タスクStateや追加・削除処理はReactのHookを使うため`hooks`です。
  • LocalStorageから読み込む・保存する処理は`services`です。
  • 検索やフィルターは、Reactを使わない関数として`utils`に置けます。
  • タスクやフィルターのデータ構造は`types`に置きます。

移動するときは、いきなりすべてを書き換えず、ひとつの役割を移動して、アプリが動くか確認するのが安全です。

2. TypeScript用のフォルダー構成を作る

今回はTypeScriptを使うNext.jsプロジェクトを想定し、.tsxと.tsで例を示します。すでにJavaScriptのプロジェクトを使っている場合、型定義ファイルはなくても構いません。

src/
├── app/
│   └── page.tsx
├── components/
│   └── tasks/
│       ├── TaskForm.tsx
│       └── TaskList.tsx
├── hooks/
│   └── useTasks.ts
├── services/
│   └── taskStorage.ts
├── utils/
│   └── filterTasks.ts
└── types/
    └── task.ts

プロジェクトがsrcを使っていない場合は、同じ構成をルートに置けます。フォルダー名よりも、チームやプロジェクト内で一貫していることが大切です。

3. types:データの形を定義する

まずsrc/types/task.tsに、タスクとフィルターの型を定義します。

// タスクで使用できるカテゴリーを定義します
export type TaskCategory = "work" | "study" | "personal";

// 完了状態のフィルターを定義します
export type TaskStatusFilter = "all" | "active" | "completed";

// カテゴリーフィルターを定義します
export type TaskCategoryFilter = "all" | TaskCategory;

// タスク1件のデータ構造を定義します
export type Task = {
  id: string;
  title: string;
  category: TaskCategory;
  completed: boolean;
  createdAt: number;
};

// 検索・絞り込みに使う条件を定義します
export type TaskFilters = {
  query: string;
  status: TaskStatusFilter;
  category: TaskCategoryFilter;
};
TypeScript

Taskという型を定義すると、タスクに必要な項目がコード上で分かります。たとえばcompletedを文字列で渡すなど、意図しないデータを作ったときに、TypeScriptが気づく手助けをしてくれます。

型定義は実行時にデータを検証する仕組みではありません。LocalStorageやAPIから読み込むデータは、実際の値を別途チェックする必要があります。

4. services:LocalStorageとのやり取りを分ける

src/services/taskStorage.tsに、タスクの読み書きをまとめます。LocalStorageはブラウザーにある機能なので、サーバー側で実行される可能性のある場所から直接呼び出さないようにします。この例では、サービス関数をブラウザー側のEffectから呼び出します。

// Task型を読み込みます
import type { Task } from "../types/task";

// LocalStorageに使うキーです
const STORAGE_KEY = "day32-tasks";

// LocalStorageから読み込んだ値がTaskの形か確認します
function isTask(value: unknown): value is Task {
  // nullや配列など、オブジェクト以外を除外します
  if (typeof value !== "object" || value === null) {
    return false;
  }

  // プロパティを確認できる形にします
  const task = value as Record<string, unknown>;

  // 必須項目の型とカテゴリーを確認します
  return (
    typeof task.id === "string" &&
    typeof task.title === "string" &&
    (task.category === "work" ||
      task.category === "study" ||
      task.category === "personal") &&
    typeof task.completed === "boolean" &&
    typeof task.createdAt === "number"
  );
}

// LocalStorageからタスク一覧を読み込みます
export function loadTasks(): Task[] {
  // この関数はブラウザー上で呼び出す前提です
  const savedText = window.localStorage.getItem(STORAGE_KEY);

  // 保存データがない場合は空配列を返します
  if (savedText === null) {
    return [];
  }

  // JSON文字列をJavaScriptの値に戻します
  const parsed: unknown = JSON.parse(savedText);

  // 配列でなければ形式エラーとして扱います
  if (!Array.isArray(parsed)) {
    throw new Error("保存データがタスク一覧の形式ではありません。");
  }

  // 要素を1件ずつ検証します
  if (!parsed.every(isTask)) {
    throw new Error("保存データに不正なタスクが含まれています。");
  }

  // 検証済みの値をタスク一覧として返します
  return parsed;
}

// タスク一覧をLocalStorageに保存します
export function saveTasks(tasks: Task[]): void {
  // タスク一覧をJSON文字列に変換して保存します
  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tasks));
}
TypeScript

このサービスは読み込みや保存を担当しますが、ReactのStateは持ちません。役割を分けることで、LocalStorageの保存方法を変更したときに、画面部品を大きく書き換えずに済みます。

JSON.parse()が失敗した場合や、ブラウザーの設定でLocalStorageが使えない場合は例外が発生することがあります。次のHookでエラーを受け取り、アプリを止めずに案内します。

5. utils:検索・フィルターの純粋な処理を分ける

src/utils/filterTasks.tsには、タスク配列を条件で絞り込む関数を置きます。この関数はReactやブラウザー機能に依存しません。同じ入力なら同じ結果を返すので、単体でテストしやすい処理です。

// Taskとフィルターの型を読み込みます
import type { Task, TaskFilters } from "../types/task";

// 検索条件に合うタスクだけを返します
export function filterTasks(
  tasks: Task[],
  filters: TaskFilters
): Task[] {
  // 検索語の前後の空白を取り、小文字にそろえます
  const query = filters.query.trim().toLowerCase();

  // 条件に合わないタスクを除外します
  return tasks.filter((task) => {
    // タスク名に検索語が含まれるか確認します
    const matchesQuery = task.title.toLowerCase().includes(query);

    // 完了状態の条件を確認します
    const matchesStatus =
      filters.status === "all" ||
      (filters.status === "active" && !task.completed) ||
      (filters.status === "completed" && task.completed);

    // カテゴリーの条件を確認します
    const matchesCategory =
      filters.category === "all" ||
      task.category === filters.category;

    // すべての条件に合うタスクだけ表示対象にします
    return matchesQuery && matchesStatus && matchesCategory;
  });
}
TypeScript

検索結果を別のStateに保存する必要はありません。タスク一覧とフィルターから計算できる値なので、表示時に計算します。表示処理が重いと計測で分かった場合に、useMemoの追加を検討できます。

6. hooks:Stateと操作をまとめる

src/hooks/useTasks.tsでは、タスクのState、読み込み、保存、追加、完了切り替え、削除を管理します。

// ReactのStateとEffectを読み込みます
import { useEffect, useState } from "react";

// 保存サービスを読み込みます
import { loadTasks, saveTasks } from "../services/taskStorage";

// TaskとTaskCategory型を読み込みます
import type { Task, TaskCategory } from "../types/task";

// タスク管理をまとめるカスタムHookです
export function useTasks() {
  // タスク一覧を管理します
  const [tasks, setTasks] = useState<Task[]>([]);

  // 初回の保存データ読み込みが終わったか管理します
  const [isReady, setIsReady] = useState(false);

  // LocalStorageの読み込みに成功したかを管理します
  const [canSave, setCanSave] = useState(false);

  // 利用者に伝えるメッセージを管理します
  const [message, setMessage] = useState("");

  // 初回表示後にLocalStorageから読み込みます
  useEffect(() => {
    try {
      // 保存データを取得してStateに設定します
      const savedTasks = loadTasks();
      setTasks(savedTasks);

      // 読み込みに成功したら保存を有効にします
      setCanSave(true);
    } catch {
      // 保存データが使えない場合の案内です
      setMessage("保存データを読み込めませんでした。");

      // 読み込みに失敗した状態では既存データを上書きしません
      setCanSave(false);
    } finally {
      // 読み込み処理が終了したことを記録します
      setIsReady(true);
    }
  }, []);

  // 読み込み成功後、タスクが変わったら保存します
  useEffect(() => {
    // 読み込み前や読み込み失敗時には保存しません
    if (!isReady || !canSave) {
      return;
    }

    try {
      // 現在のタスク一覧を保存します
      saveTasks(tasks);
    } catch {
      // 保存失敗を画面に伝えます
      setMessage("タスクをブラウザーに保存できませんでした。");
    }
  }, [tasks, isReady, canSave]);

  // 新しいタスクを追加します
  function addTask(title: string, category: TaskCategory) {
    // 入力の前後の空白を取り除きます
    const trimmedTitle = title.trim();

    // 空のタイトルは追加しません
    if (trimmedTitle === "") {
      setMessage("タスク名を入力してください。");
      return;
    }

    // 新しいタスクを作ります
    const newTask: Task = {
      id: crypto.randomUUID(),
      title: trimmedTitle,
      category,
      completed: false,
      createdAt: Date.now(),
    };

    // 既存Stateを直接変更せず、新しい配列を作ります
    setTasks((currentTasks) => [...currentTasks, newTask]);

    // 古い案内を消します
    setMessage("");
  }

  // 指定したタスクの完了状態を切り替えます
  function toggleTask(taskId: string) {
    // 対象タスクだけ新しいオブジェクトに置き換えます
    setTasks((currentTasks) =>
      currentTasks.map((task) =>
        task.id === taskId
          ? { ...task, completed: !task.completed }
          : task
      )
    );
  }

  // 指定したタスクを削除します
  function deleteTask(taskId: string) {
    // 対象以外のタスクから新しい配列を作ります
    setTasks((currentTasks) =>
      currentTasks.filter((task) => task.id !== taskId)
    );
  }

  // 画面で必要な値と操作関数を返します
  return {
    tasks,
    isReady,
    message,
    addTask,
    toggleTask,
    deleteTask,
  };
}
TypeScript

HookはStateとReactのEffectを使う処理をまとめています。ただし、useTasks()を複数のコンポーネントから個別に呼んでも、Stateが自動的に共有されるわけではありません。この例ではページで一度呼び出し、値や関数を子へPropsで渡します。

7. components:画面の部品を作る

タスク追加フォーム

src/components/tasks/TaskForm.tsxを作ります。フォームの入力値はこのコンポーネントだけで使うため、ここにLocal Stateとして置きます。

// この部品は入力イベントとStateを使います
"use client";

// フォーム入力用のState機能を読み込みます
import { useState } from "react";

// カテゴリーの型を読み込みます
import type { TaskCategory } from "../../types/task";

// 親から受け取るPropsの型です
type TaskFormProps = {
  onAdd: (title: string, category: TaskCategory) => void;
};

// タスク追加フォームを表示します
export default function TaskForm({ onAdd }: TaskFormProps) {
  // タスク名の入力値を管理します
  const [title, setTitle] = useState("");

  // 選択中のカテゴリーを管理します
  const [category, setCategory] = useState<TaskCategory>("study");

  // フォーム送信を処理します
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    // ページの再読み込みを防ぎます
    event.preventDefault();

    // 親から受け取った関数でタスクを追加します
    onAdd(title, category);

    // 送信後に入力欄を空にします
    setTitle("");
  }

  return (
    // 送信時にタスク追加関数を呼び出します
    <form onSubmit={handleSubmit}>
      <label htmlFor="task-title">タスク名</label>

      <input
        id="task-title"
        value={title}
        onChange={(event) => setTitle(event.target.value)}
        maxLength={100}
        required
      />

      <label htmlFor="task-category">カテゴリー</label>

      <select
        id="task-category"
        value={category}
        onChange={(event) =>
          setCategory(event.target.value as TaskCategory)
        }
      >
        <option value="work">仕事</option>
        <option value="study">学習</option>
        <option value="personal">プライベート</option>
      </select>

      <button type="submit">追加</button>
    </form>
  );
}
TSX

フォームのtitleとcategoryはこの部品内だけで使うため、Hookに移していません。使う範囲がひとつの部品なら、Stateもその部品に置くと責務が分かりやすくなります。

タスク一覧

src/components/tasks/TaskList.tsxを作ります。ここではタスクを一覧表示し、完了と削除の操作を親へ伝えます。

// Task型を読み込みます
import type { Task } from "../../types/task";

// タスク一覧のPropsの型です
type TaskListProps = {
  tasks: Task[];
  onToggle: (taskId: string) => void;
  onDelete: (taskId: string) => void;
};

// タスク一覧を表示します
export default function TaskList({
  tasks,
  onToggle,
  onDelete,
}: TaskListProps) {
  // 表示対象がない場合の案内を返します
  if (tasks.length === 0) {
    return <p>表示するタスクはありません。</p>;
  }

  return (
    <ul>
      {tasks.map((task) => (
        // タスクごとの安定したIDをkeyに使います
        <li key={task.id}>
          <label>
            <input
              type="checkbox"
              checked={task.completed}
              // 完了状態の変更を親へ伝えます
              onChange={() => onToggle(task.id)}
            />

            <span>
              {task.title}({task.category})
            </span>
          </label>

          <button
            type="button"
            // 削除操作を親へ伝えます
            onClick={() => onDelete(task.id)}
          >
            削除
          </button>
        </li>
      ))}
    </ul>
  );
}
TSX

このコンポーネントはLocalStorageを知りません。受け取ったタスクを表示し、操作があれば親へ伝えます。画面表示と保存処理を分けることで、表示の変更が保存ロジックに影響しにくくなります。

8. app/page.tsxで組み立てる

最後に、ページでHookとコンポーネントを組み合わせます。filterTasksは純粋な関数なので、検索条件に合うタスクをページ内で計算できます。

// タスクフォームと一覧を読み込みます
import TaskForm from "../components/tasks/TaskForm";
import TaskList from "../components/tasks/TaskList";

// タスク管理Hookを読み込みます
import { useTasks } from "../hooks/useTasks";

// フィルター関数を読み込みます
import { filterTasks } from "../utils/filterTasks";

// フィルター型を読み込みます
import type { TaskFilters } from "../types/task";

// ページでHookと画面部品を組み合わせます
export default function HomePage() {
  // タスクの状態と操作をHookから受け取ります
  const {
    tasks,
    isReady,
    message,
    addTask,
    toggleTask,
    deleteTask,
  } = useTasks();

  // 検索・絞り込み条件を管理します
  const [filters, setFilters] = useState<TaskFilters>({
    query: "",
    status: "all",
    category: "all",
  });

  // 現在の条件に合うタスクを計算します
  const visibleTasks = filterTasks(tasks, filters);

  // LocalStorage読み込み中の画面を表示します
  if (!isReady) {
    return <p>保存したタスクを読み込んでいます...</p>;
  }

  return (
    <main>
      <h1>タスク管理</h1>

      {/* フォームからの追加処理をHookへ渡します */}
      <TaskForm onAdd={addTask} />

      <section>
        <label htmlFor="task-search">タスク名で検索</label>

        <input
          id="task-search"
          value={filters.query}
          onChange={(event) =>
            setFilters((current) => ({
              ...current,
              query: event.target.value,
            }))
          }
        />

        <label htmlFor="task-status">完了状態</label>

        <select
          id="task-status"
          value={filters.status}
          onChange={(event) =>
            setFilters((current) => ({
              ...current,
              status: event.target.value as TaskFilters["status"],
            }))
          }
        >
          <option value="all">すべて</option>
          <option value="active">未完了</option>
          <option value="completed">完了済み</option>
        </select>
      </section>

      {/* 保存や入力に関する案内を表示します */}
      <p aria-live="polite">{message}</p>

      {/* 一覧と操作関数を表示部品へ渡します */}
      <TaskList
        tasks={visibleTasks}
        onToggle={toggleTask}
        onDelete={deleteTask}
      />
    </main>
  );
}
TSX

このコードではuseStateも使うため、ファイル先頭に"use client";が必要です。忘れずに追加してください。

// このファイルの先頭に置くClient Component宣言です
"use client";

// 続けてReact Hookやコンポーネントをimportします
TSX

Next.jsでは、Stateやイベント処理を使う部分をClient Componentにします。ページ全体をClient Componentにする必要がない場合は、必要な範囲だけをクライアント側にする設計も検討できます。

9. 各フォルダーの役割を見分ける

迷ったら、そのコードが何をしているかを短い文で説明します。

  • 「画面の見た目を返す」なら、まず`components`を検討します。
  • 「React StateやEffectを使い、状態と操作をまとめる」なら、`hooks`を検討します。
  • 「LocalStorageやAPIなど、外部とやり取りする」なら、`services`を検討します。
  • 「引数を受け取り、加工した値を返すだけ」なら、`utils`を検討します。
  • 「データや関数の型を宣言する」なら、`types`を検討します。

フォルダー名は目安です。迷ったときは、他のコードから呼び出される方向や、外部サービスへの依存がどこにあるかを考えると整理しやすくなります。

10. 依存関係を一方向に保つ

初心者のうちは、依存関係を次のような流れにすると理解しやすくなります。

page
 ├── components
 └── hooks
      ├── services
      └── utils

components / hooks / services / utils
 └── types

たとえば、utilsが画面コンポーネントを読み込んだり、servicesがページを読み込んだりする構成は避けます。役割が逆転すると、ファイル同士の依存が複雑になり、変更の影響を追いにくくなります。

11. 分割後の確認手順

ファイルを移動したら、次の操作をひとつずつ試します。

  • アプリが起動し、ページが表示されます。
  • タスクを追加できます。
  • 完了状態を切り替えられます。
  • タスクを削除できます。
  • 検索・フィルターで表示内容が変わります。
  • ページを再読み込みしても保存データが読み込まれます。
  • ブラウザーのConsoleとターミナルにエラーが出ていません。

すべてを移動した後にだけ確認するのではなく、段階ごとに動作を確かめると、問題が起きたときに原因を特定しやすくなります。

12. よくあるつまずき

  • ファイルを分けたのに役割が混ざっている:コンポーネントがLocalStorageを直接操作するなど、責務が重なっていないか確認します。
  • ユーティリティ関数でHookを呼ぶ:HookはReactコンポーネントかカスタムHookで使います。純粋な`utils`関数では呼びません。
  • 型があるから保存データも安全だと思う:TypeScriptの型は実行時の検証ではありません。外部データは実際に検査します。
  • LocalStorageをサーバー側で使ってしまう:ブラウザー機能なので、Client ComponentのEffectやイベント処理から呼び出します。
  • フォルダーを細かくしすぎる:小さな処理まで無理に分割すると、ファイルを行き来する負担が増えます。
  • 一度にすべてを移動する:段階的に移動して、各段階でアプリを動かして確認します。

13. Day 32のチェックリスト

  • 表示部品を`components`に整理できます。
  • StateとReactの副作用を`hooks`にまとめられます。
  • LocalStorageやAPIとのやり取りを`services`に分けられます。
  • Reactに依存しない加工処理を`utils`に分けられます。
  • TypeScriptの型を`types`にまとめられます。
  • TypeScriptの型と実行時のデータ検証の違いを説明できます。
  • 変更後に追加・更新・削除・絞り込み・保存を確認できます。

設計演習では、決まったフォルダー名にコードを押し込むことより、役割と依存関係を分かりやすくすることが大切です。今回のタスクアプリでは、画面、Reactの状態、ブラウザー保存、検索処理、データ型を分けました。まずはこの構成を動かし、次にタスク編集やカテゴリー絞り込みを追加して、どの役割にコードを置くと読みやすいか考えてみましょう。

タイトルとURLをコピーしました