Как использовать 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.tsx | 404 | «Не найдено» + ссылка |
| Не вошёл | redirect("/login") или unauthorized() | 307 / 401 | Страница входа |
| Нет прав | forbidden() → forbidden.tsx | 403 | «Нет доступа» |
| Ошибка ввода в форме | return { errors } из Action | 200 | Текст у поля |
| БД недоступна, баг | throw → error.tsx | 500 | «Не удалось» + повтор |
| Ошибка в корневом layout | global-error.tsx | 500 | Отдельный документ |
Нюансы
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.