Проект: план, маршруты и раскладки

Список умений почти не изменился с части II, но проверять их теперь придётся иначе: не «карточка появилась на странице», а «по адресу открылось то, что нужно». Адрес — новая часть договора, и он же главная причина переезда на Next.js: на задачу можно дать ссылку.

И сразу — чего в проекте не будет. Ни входа по паролю, ни настоящей базы: список задач будет лежать в памяти сервера. Ни перетаскивания мышью, ни анимаций. Этого достаточно, чтобы пройти серверные компоненты, действия и выкладку, и мало, чтобы утонуть в постороннем.

Разница с частью II глубже, чем «добавились адреса». Там страница приходила пустой, а список рисовал render() в браузере — из localStorage. Здесь первый же кадр приезжает с задачами внутри, потому что компонент доски выполняется на сервере: как это работает, разбирали статьи «Серверный компонент: код, который не уехал в браузер» и «Данные прямо в компоненте: await вместо useEffect».

Многофайловый проект песочница не запускает: в ней нет ни Next, ни файловой системы, ни сервера. Всё, что можно проверить одним файлом, ниже запускается по-настоящему; остальное — настоящие файлы проекта: компилятор их проверит, а выполнять будет нечего. Там, где так, это сказано прямо, а не замаскировано.

Первое решение вообще не про React. Пока форма задачи не описана в одном месте, каждый файл придумывает её заново: где-то status — строка, где-то число, а где-то поле называется state. В части III это лечилось одним приёмом — тип как договор; здесь договор нужен ещё и потому, что данные поедут через границу сервер — браузер.

// src/task/task.types.ts — единственное место, где описан договор о данных
type Status = "todo" | "doing" | "done";

interface Task {
  id: string;
  title: string;
  status: Status;
  createdAt: string;
}

// в форме пользователь заполняет только это: id и дату проставит сервер
type NewTask = Omit<Task, "id" | "createdAt">;

// заголовки колонок: полноту набора проверяет компилятор, а не наша память
const COLUMNS: Record<Status, string> = {
  todo: "Сделать",
  doing: "В работе",
  done: "Готово"
};

const tasks: Task[] = [
  { id: "t1", title: "Сверстать доску", status: "todo", createdAt: "2026-09-01" },
  { id: "t2", title: "Написать раскладку", status: "doing", createdAt: "2026-09-02" },
  { id: "t3", title: "Прочитать главу", status: "todo", createdAt: "2026-09-03" }
];

const byStatus = (status: Status): Task[] => tasks.filter((task) => task.status === status);

console.log(COLUMNS.doing);
console.log(byStatus("todo").length);
console.log(byStatus("done").length);

const draft: NewTask = { title: "Выложить проект", status: "todo" };
console.log(Object.keys(draft).join(","));

Три решения в этом файле стоит назвать вслух. Status — объединение литералов, а не string: список колонок конечен, и компилятор об этом знает. NewTask получен из Task через Omit, а не выписан руками — иначе два типа однажды разъедутся. COLUMNS — это Record<Status, string>, то есть обещание, что заголовок есть у каждого статуса.

Последнее обещание и проверим. В доску добавляют колонку «На проверке» — правится ровно один тип. Прежде чем нажать Run, решите: на какую строку покажет компилятор?

// в доску добавили колонку «На проверке» — правим один тип
type Status = "todo" | "doing" | "review" | "done";

const COLUMNS: Record<Status, string> = {
  todo: "Сделать",
  doing: "В работе",
  done: "Готово"
};

console.log(Object.keys(COLUMNS).length);

Он показывает на объявление COLUMNS, а не на место, где заголовок понадобился. Это и есть польза от Record: правка типа сама приводит к списку мест, которые обязаны догнать. Вторая строка при этом всё равно печатается — типы до выполнения не доживают, а tsc по умолчанию собирает код даже с ошибками.

id задачи — строка, хотя в базе он однажды может стать числом. Причина простая: в адресе он всё равно строка, и лишний Number(params.id) — лишний повод ошибиться.

Адрес в App Router — это папка, и другого источника правды у него нет: правило разбирала статья «App Router: адрес — это папка». Значит, спроектировать маршруты — буквально нарисовать дерево папок. Вот наше.

Соберём адреса из этого списка тем же способом, каким это делает Next при старте, — и заодно увидим, какие файлы адресов не дают.

// так лежат файлы проекта — адрес из них даёт не каждый
const files = [
  "app/layout.tsx",
  "app/page.tsx",
  "app/tasks/layout.tsx",
  "app/tasks/[id]/page.tsx",
  "app/tasks/[id]/edit/page.tsx",
  "app/tasks/[id]/not-found.tsx",
  "src/ui/task-card/task-card.tsx"
];

const routes = files
  .filter((file) => file.startsWith("app/") && file.endsWith("/page.tsx"))
  .map((file) => "/" + file.slice("app/".length, -"/page.tsx".length));

console.log(routes.length);
console.log(routes.join(" | "));

Семь файлов — три адреса. Ни layout.tsx, ни not-found.tsx адреса не создают: зарезервированное имя меняет поведение папки, но сегментом не становится. А всё, что лежит вне app, маршрутизатор не смотрит вовсе: компоненты живут в src и попадают на страницу только импортом.

Теперь обратный ход: по адресу найти маршрут. Квадратные скобки — дырка под любое значение, поэтому сравнивать нужно посегментно. Перед запуском ответьте на последний вопрос примера: что откроется по /tasks?

const routes = ["/", "/tasks/[id]", "/tasks/[id]/edit"];

// сегмент в квадратных скобках подходит под любое значение — это и есть [id]
function resolve(url: string): string {
  const parts = url.split("/").filter(Boolean);
  const found = routes.find((route) => {
    const segments = route.split("/").filter(Boolean);
    return (
      segments.length === parts.length &&
      segments.every((segment, i) => segment.startsWith("[") || segment === parts[i])
    );
  });
  return found ?? "404";
}

console.log(resolve("/"));
console.log(resolve("/tasks/t1"));
console.log(resolve("/tasks/t1/edit"));
console.log(resolve("/tasks"));

По /tasks — 404, хотя папка app/tasks в проекте есть и раскладка в ней тоже. Папка без page.tsx адреса не даёт, и это не недосмотр плана: отдельного экрана «все задачи списком» у нас нет, потому что доска и есть этот список. Если бы он понадобился, лечилось бы одним файлом.

Компоненты в дереве маршрутов не живут. В app лежат только страницы и раскладки, всё остальное — рядом, в src, папками по имени модуля: src/ui/task-card/task-card.tsx, рядом с ним task-card.module.css и task-card.types.ts. Стили и сборка — тема последней статьи главы, но место для них выбирается сейчас.

Раскладок в проекте две, и уровень каждой задан папкой — так же, как адрес. Корневая обязательна и единственная, где встречаются <html> и <body>.

// app/layout.tsx — единственный файл проекта, где встречаются html и body
function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ru">
      <body>
        <header>
          <a href="/">Доска задач</a>
        </header>
        <main>{children}</main>
      </body>
    </html>
  );
}

В настоящем файле перед функцией стоит export default: Next импортирует страницы и раскладки сам, и договариваться об имени ему не с кем. В примерах это слово опущено — песочница выполняет один файл без модулей.

Этот пример ничего не печатает и ничего не рисует: <html> внутрь страницы песочницы не смонтировать. Компилятор его при этом проверил — и на том спасибо; подделывать запуск мы не станем.

Вторая раскладка — на папке tasks. Она обнимает и страницу задачи, и форму правки: у обеих узкая колонка и одинаковый путь назад. Вот эта пара уже запускается.

// app/tasks/layout.tsx — узкая колонка и путь назад: общие для всех страниц задачи
function TasksLayout({ children }: { children: React.ReactNode }) {
  return (
    <div style={{ maxWidth: 360, border: "1px solid #999", padding: 12 }}>
      <a href="/">← к доске</a>
      {children}
    </div>
  );
}

// app/tasks/[id]/page.tsx — данные приедут в следующей статье, пока они вписаны руками
function TaskPage() {
  return (
    <article>
      <h1>Сверстать доску</h1>
      <p>Статус: Сделать</p>
    </article>
  );
}

// эту пару Next собирает сам — по дереву папок
ReactDOM.createRoot(document.getElementById("root")!).render(
  <TasksLayout>
    <TaskPage />
  </TasksLayout>
);

Ссылка «к доске» лежит именно в раскладке, а не в двух страницах — и дело не в экономии четырёх строк. При переходе с /tasks/t1 на /tasks/t1/edit общая часть цепочки не пересоздаётся: раскладка остаётся смонтированной, меняется только хвост. Что переживает переход, а что сбрасывается, разбирала статья «Вложенные раскладки, группы и шаблоны».

Осталась сама доска. Три колонки — не три копии разметки, а цикл по списку статусов: заголовки берутся из COLUMNS, порядок — из отдельного массива.

type Status = "todo" | "doing" | "done";

interface Task {
  id: string;
  title: string;
  status: Status;
}

interface ColumnProps {
  status: Status;
  tasks: Task[];
}

const COLUMNS: Record<Status, string> = {
  todo: "Сделать",
  doing: "В работе",
  done: "Готово"
};

// порядок колонок — тоже данные: в разметке его нет
const ORDER: Status[] = ["todo", "doing", "done"];

// src/ui/board-column/board-column.tsx
function Column({ status, tasks }: ColumnProps) {
  const own = tasks.filter((task) => task.status === status);
  return (
    <section style={{ border: "1px solid #999", padding: 8, minWidth: 130 }}>
      <h3>{COLUMNS[status]} ({own.length})</h3>
      <ul>
        {own.map((task) => (
          <li key={task.id}>
            <a href={"/tasks/" + task.id}>{task.title}</a>
          </li>
        ))}
      </ul>
    </section>
  );
}

// app/page.tsx — доска: колонки рисуются циклом, а не тремя копиями разметки
function BoardPage() {
  const tasks: Task[] = [
    { id: "t1", title: "Сверстать доску", status: "todo" },
    { id: "t2", title: "Написать раскладку", status: "doing" },
    { id: "t3", title: "Прочитать главу", status: "todo" }
  ];
  return (
    <div style={{ display: "flex", gap: 8 }}>
      {ORDER.map((status) => (
        <Column key={status} status={status} tasks={tasks} />
      ))}
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<BoardPage />);

В кадре — каркас будущей доски: колонки, счётчики и ссылки на страницы задач. Данные пока вписаны прямо в компонент, и это честный шаг плана: разметку видно, а откуда возьмётся массив tasks, решает следующая статья главы.

Пропсы Column описаны типом не ради красоты. Вот что происходит, если в разметке появится колонка, которой нет в плане.

type Status = "todo" | "doing" | "done";

interface ColumnProps {
  status: Status;
  title: string;
}

function Column({ status, title }: ColumnProps) {
  return (
    <section data-status={status}>
      <h3>{title}</h3>
    </section>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <Column status="archived" title="Архив" />
);

Компилятор говорит об этом до запуска, а браузер потом всё равно рисует пустой «Архив» — ошибка типов выполнение не отменяет. Разница в том, где вы об этом узнаете: в редакторе через секунду или на живой доске через неделю.

Третье решение плана — самое дорогое при ошибке. Директива 'use client' красит не файл, а всё поддерево его импортов: почему так, разбирала статья «Граница 'use client' и почему она заразна». Поэтому спрашивать надо не «какой компонент интерактивный», а «что уедет в браузер вместе с ним».

Пройдёмся по доске. Кнопка «дальше» на карточке меняет данные — значит, это форма с серверным действием, и состояния в браузере ей не нужно. Форма добавления — тоже. А вот живой фильтр по названию, который прячет карточки прямо во время набора, без состояния не работает: он и станет островком.

Посчитаем цену обоих решений. Перед запуском прикиньте: сколько файлов уедет в браузер во втором случае?

interface FileNode {
  path: string;
  directive: boolean; // стоит ли "use client" первой строкой файла
  imports: string[];
}

const tree: FileNode[] = [
  { path: "app/page.tsx", directive: false, imports: ["board-column", "task-filter"] },
  { path: "board-column", directive: false, imports: ["task-card"] },
  { path: "task-card", directive: false, imports: [] },
  { path: "task-filter", directive: true, imports: [] }
];

// в браузер уезжает файл с директивой и всё, что он тянет за собой вниз
function clientFiles(nodes: FileNode[]): string[] {
  const byPath = new Map<string, FileNode>(nodes.map((node) => [node.path, node]));
  const queue = nodes.filter((node) => node.directive).map((node) => node.path);
  const client = new Set<string>();
  while (queue.length > 0) {
    const path = queue.shift()!;
    if (client.has(path)) continue;
    client.add(path);
    for (const name of byPath.get(path)?.imports ?? []) queue.push(name);
  }
  return [...client];
}

console.log(clientFiles(tree).join(", "));

// а теперь директиву поставили на страницу доски — «чтобы фильтр заработал»
const wrong = tree.map((node) =>
  node.path === "app/page.tsx" ? { ...node, directive: true } : node
);
console.log(clientFiles(wrong).length);

Один файл против всех четырёх — и это на игрушечном дереве из четырёх узлов. В настоящем проекте «поставлю директиву повыше, чтобы не мучиться» отправляет в браузер половину приложения вместе с разметкой, которая могла остаться на сервере. Отсюда правило плана: директива ставится на самый мелкий лист, какой получится, а серверная разметка попадает внутрь островка через children — приём из статьи «Что можно передать через границу».

В песочнице всё выполняется в браузере — сервера в ней нет. Поэтому граница здесь только считается, а не наблюдается: примеры про неё показывают решение, а не его последствия.

План есть — осталось решить, в каком порядке он превращается в код. Порядок тот же, что был в части II, и по той же причине: каждый следующий шаг проверяется по уже работающему предыдущему, а не по обещанию.

Первый шаг — эта статья: дерево нарисовано, типы описаны, каркас доски рисуется. Начинать с данных было бы соблазнительно, но тогда отлаживаются сразу две несуществующие вещи, и непонятно, что именно сломалось — запрос или разметка.

И последнее решение плана, которое стоит проговорить: пока данных нет, они вписаны прямо в компонент — массивом, как в примерах выше. Это не «времянка, которую потом заменим», а способ проверить разметку отдельно от источника. Заменить массив на чтение с сервера — работа следующей статьи, и она займёт несколько строк.