Based on the official Next.js documentation (specifically the App Router API Reference), Next.js 16 utilizes a set of “special files” (file-system conventions) to define the UI and behavior of your application’s routes.
These files must be placed inside the app directory. Here is an explanation of every default page and special file available in the App Router:
1. Core Routing & UI
These files are the building blocks of your application’s visual structure.
page.js (.jsx, .tsx)
Role: The unique UI for a route.
Description: This is the only file required to make a route public. It allows you to define the UI that is specific to that URL segment (e.g., app/dashboard/page.js renders the UI for /dashboard).
layout.js (.jsx, .tsx)
Role: Shared UI for a segment and its children.
Description: A layout wraps pages and other layouts. It preserves state, remains interactive, and does not re-render when navigating between sibling routes. The root app/layout.js is mandatory and must define the <html> and <body> tags.
template.js (.jsx, .tsx)
Role: A specialized layout that resets on navigation.
Description: Similar to layout.js, it wraps each child layout or page. However, unlike layouts, a template creates a new instance for each of its children on navigation. This means state is not preserved, and effects are re-synchronized.
2. Loading & Error Handling
These files allow you to handle asynchronous states and runtime errors gracefully.
loading.js (.jsx, .tsx)
Role: Loading UI (React Suspense Boundary).
Description: Automatically wraps the page or child route in a React Suspense boundary. It shows this UI immediately while the route segment’s content loads, enabling instant loading states (like skeletons or spinners).
error.js (.jsx, .tsx)
Role: Error UI (React Error Boundary).
Description: Automatically wraps the route segment in a React Error Boundary. It allows you to define a custom error UI for a specific segment, isolating errors so the rest of the app remains functional. It must be a Client Component (‘use client’).
not-found.js (.jsx, .tsx)
Role: 404 Not Found UI.
Description: Rendered when the notFound() function is thrown within a route segment, or when a URL does not match any route.
global-error.js (.jsx, .tsx)
Role: Global Error UI.
Description: Used specifically to catch errors in the root app/layout.js. Since error.js is nested inside the layout, it cannot catch errors thrown by the root layout itself. global-error.js replaces the entire root layout when active and must define its own <html> and <body> tags.
3. Authentication & Access Control (Newer Additions)
These special files handle specific HTTP status scenarios related to permissions.
forbidden.js (.jsx, .tsx)
Role: 403 Forbidden UI.
Description: Rendered when the forbidden() function is invoked. It is used to show a custom UI when a user is authenticated but not authorized to access a specific resource.
unauthorized.js (.jsx, .tsx)
Role: 401 Unauthorized UI.
Description: Rendered when the unauthorized() function is invoked. This is typically used to prompt a user to log in if they try to access a protected route without valid credentials.
4. Advanced Routing & API
These files handle complex routing patterns and server-side logic.
default.js (.jsx, .tsx)
Role: Fallback UI for Parallel Routes.
Description: Used specifically with Parallel Routes (defined with @folder). Next.js uses this file to render a fallback UI when it cannot recover a slot’s active state after a hard reload (or if a slot lacks a matching route for the current URL).
route.js (.js, .ts)
Role: Server-side API Endpoint.
Description: Allows you to create custom request handlers for a given route using the Web Request and Response APIs. It replaces the pages/api directory from older versions. You cannot have a route.js and a page.js at the same route segment level, as they would conflict.
File Purpose:
page.js: Main UI for a specific route.
layout.js: Shared UI that wraps pages (persists state).
loading.js: UI shown while the route content is loading.
not-found.js: UI shown for 404 errors.
error.js: UI shown for runtime errors in a segment.
global-error.js: UI shown for errors in the root layout.
route.js: API endpoint (returns JSON/Response, not UI).
template.js: Wraps pages but resets state on navigation.
default.js: Fallback UI for Parallel Routes.
forbidden.js: UI for 403 Forbidden errors.
unauthorized.js: UI for 401 Unauthorized errors.