App Router File Conventions
The App Router utilizes a hierarchical, folder-based routing engine built directly on React Server Component specifications.Learn how layout.tsx preserves client state across route changes while template.tsx remounts, how error boundaries isolate widget crashes without breaking root navigation, and how default.tsx resolves parallel slots.Master the exact file conventions required to organize complex multi-surface enterprise applications.
The Route Hierarchy: Layouts, Templates, and Pages
Layouts (layout.tsx) wrap page hierarchies, preserve client state across navigations, and do not re-render their DOM on route changes. Templates (template.tsx) create a new instance on every navigation, resetting state and DOM, which is essential for page enter animations and reset-on-navigation behaviors.
Route Groups and Multiple Root Layouts
Route groups wrap folder names in parentheses, such as (marketing) and (dashboard), organizing files and layouts without affecting the public URL path. They allow developers to create multiple root layouts with completely different <html> and <body> tags in the same application.
Declarative Loading States with loading.tsx
loading.tsx automatically wraps the sibling page.tsx and nested children inside an implicit React Suspense boundary. It displays an instant loading skeleton during server rendering and route transitions, providing immediate visual feedback without manual client loading states.
Granular Error Handling with error.tsx and global-error.tsx
error.tsx defines an isolated React Error Boundary around sibling page segments, allowing crashes to be caught without breaking the outer layout. It must be a Client Component and receives error and reset props. To catch errors in the root layout itself, Next.js requires global-error.tsx defining its own <html> and <body> tags.
Not-Found Handling: not-found.tsx and notFound()
not-found.tsx renders a custom 404 UI for unmatched URLs or when programmatically triggered via notFound(). When invoked during server rendering, Next.js emits an HTTP 404 status code header to search engine crawlers. Like error boundaries, not-found.tsx renders inside the parent layout.
Unmatched Segments & The Role of default.tsx
default.tsx serves as the fallback view for parallel route slots (@slot) when Next.js cannot recover the slot state during a full page reload. While soft client navigation preserves the previous active slot state, hard reloads require default.tsx to prevent 404 errors for unmatched parallel segments.