re:re:actable
Урок 014 минуты чтения

Как использовать loading, error и notFound

На этой странице
Кратко

В App Router у каждого сегмента маршрута есть три специальных состояния. loading.tsx — интерфейс ожидания: Next.js оборачивает страницу сегмента в <Suspense fallback={<Loading />}>, поэтому при переходе пользователь сразу видит скелетон, а данные стримятся. error.tsx — клиентская граница непредвиденных ошибок сегмента (недоступна БД, баг в коде) с кнопкой retry() (Next 16.3+; раньше reset()). notFound() + not-found.tsx — ожидаемое отсутствие ресурса (такой задачи нет) со статусом 404. Это три разных ситуации, и смешивать их нельзя: ошибка ввода формы возвращается данными из Action, отсутствие сессии — редирект на вход (или unauthorized()), отсутствие записи — notFound(), и только реальный сбой — error.tsx.

Вопрос

Как показать загрузку, ошибку и «не найдено», если страница обращается к БД?

Как Next.js собирает сегмент

app/tasks/
├── layout.tsx
├── loading.tsx      ┐
├── error.tsx        ├─ Next.js превращает в дерево:
├── not-found.tsx    │
└── page.tsx         ┘
 
<Layout>
  <ErrorBoundary fallback={<Error />}>          ← error.tsx
    <Suspense fallback={<Loading />}>           ← loading.tsx
      <NotFoundBoundary fallback={<NotFound />}> ← not-found.tsx
        <Page />
      </NotFoundBoundary>
    </Suspense>
  </ErrorBoundary>
</Layout>

Следствие: error.tsx ловит ошибки page.tsx и вложенных сегментов, но не layout.tsx того же уровня — для него нужна граница уровнем выше или global-error.tsx.

Пример: раздел задач

// app/tasks/loading.tsx — скелетон того же размера, что список
export default function Loading() {
  return (
    <section aria-busy="true">
      <p role="status" className="visually-hidden">Загружаем задачи…</p>
      <ul aria-hidden="true">
        {Array.from({ length: 5 }, (_, i) => <li key={i} className="skeleton" style={{ height: 40 }} />)}
      </ul>
    </section>
  );
}
// app/tasks/[id]/page.tsx
import { notFound } from "next/navigation";
import { getTask } from "@/lib/dal";
 
export default async function TaskPage({ params }: PageProps<"/tasks/[id]">) {
  const { id } = await params;
  const task = await getTask(id);   // если БД упадёт — сработает error.tsx
  if (!task) notFound();            // ожидаемо: такой задачи нет → not-found.tsx, 404
  return <h1>{task.title}</h1>;
}
// app/tasks/[id]/not-found.tsx
import Link from "next/link";
 
export default function TaskNotFound() {
  return (
    <main>
      <h1>Задача не найдена</h1>
      <p>Возможно, её удалили или ссылка устарела.</p>
      <Link href="/tasks">К списку задач</Link>
    </main>
  );
}
// app/tasks/error.tsx — Next.js 16.3+
"use client";
 
import { useEffect } from "react";
 
export default function TasksError({ error, retry }: { error: unknown; retry: () => void }) {
  useEffect(() => {
    console.error(error); // в реальном проекте — отправка в мониторинг
  }, [error]);
 
  return (
    <section role="alert">
      <h1>Не удалось загрузить задачи</h1>
      <p>Попробуйте ещё раз через несколько секунд.</p>
      <button onClick={() => retry()}>Попробовать снова</button>
    </section>
  );
}

retry() перезапрашивает серверное содержимое сегмента и рендерит его заново. Старый reset() только сбрасывает состояние границы без новой загрузки данных — в версиях до 16.3 вместе с ним вызывали router.refresh().

Какой инструмент для какой ситуации

СитуацияИнструментСтатусЧто видит пользователь
Данные грузятсяloading.tsx / <Suspense>—Скелетон
Записи нетnotFound() → not-found.tsx404«Не найдено» + ссылка
Не вошёлredirect("/login") или unauthorized()307 / 401Страница входа
Нет правforbidden() → forbidden.tsx403«Нет доступа»
Ошибка ввода в формеreturn { errors } из Action200Текст у поля
БД недоступна, багthrow → error.tsx500«Не удалось» + повтор
Ошибка в корневом layoutglobal-error.tsx500Отдельный документ

Нюансы

  • loading.tsx может не появиться при переходе, если маршрут уже предзагружен — это хорошо, а не баг.
  • loading.tsx оборачивает всю страницу; для независимых медленных блоков добавляй отдельные <Suspense>.
  • Если notFound() вызван после начала стриминга (внутри Suspense), статус останется 200 — Next.js добавит noindex. Проверку существования делай до медленных частей.
  • notFound(), redirect(), forbidden() работают через специальные исключения — не перехватывай их общим try/catch.
  • Ошибки в обработчиках событий и фоновых операциях error.tsx не ловит — их обрабатывают на месте.

Что важно помнить

  • Ожидание — loading.tsx/Suspense; отсутствие — notFound(); сбой — error.tsx.
  • Ожидаемые ошибки — данные, непредвиденные — исключения.
  • retry() перезапрашивает серверные данные, reset() — нет.
  • error.tsx ниже layout своего уровня.

Мини-шпаргалка

  • Ожидание — loading.tsx или Suspense.
  • Нет ресурса — notFound() + not-found.tsx (404).
  • Непредвиденный сбой — error.tsx ("use client", retry).
  • Ошибка поля — результат Action возле формы.
  • Корневой layout — global-error.tsx.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам