Next.js App Router File Conventions: page, layout, template, and the Rest
Layouts persist and templates remount; only page.tsx and route.ts make a segment routable. Route groups, private folders, and the boundaries that catch what.

Quick Summary
The App Router is a filesystem convention. A folder under app/ becomes a route segment by its name, and the files inside it decide what that segment renders: page.tsx makes the segment publicly routable, layout.tsx wraps it and persists across navigations, template.tsx wraps it and remounts on every navigation, loading.tsx supplies a Suspense fallback, error.tsx catches render errors, not-found.tsx handles notFound(), and route.ts turns the segment into an HTTP endpoint instead of a page.
Three rules explain most of the confusion. A folder without a page.tsx or route.ts is not routable, no matter how many other files it has. The root layout is required, must be at app/layout.tsx, and must render <html> and <body>. And the hierarchy is nested, not merged: every layout between the root and the page wraps the page, and each one re-renders only when its own segment changes.
Names starting with _ are opt-outs (not routable), (name) is a route group that organises files without adding a URL segment, and @name is a parallel route slot. Those three bracket conventions are how a large app keeps URLs stable while the folder tree evolves.
Basic Syntax & Core Signatures
app/
layout.tsx # required root layout: <html> and <body>
page.tsx # "/"
globals.css
(marketing)/
layout.tsx # nested layout, no URL segment
about/page.tsx # "/about"
pricing/page.tsx # "/pricing"
(app)/
layout.tsx # a second shell: sidebar
dashboard/
layout.tsx # "/dashboard/*" wrapper
page.tsx # "/dashboard"
settings/page.tsx # "/dashboard/settings"
blog/
layout.tsx
page.tsx # "/blog"
[slug]/
page.tsx # "/blog/:slug"
loading.tsx
error.tsx
not-found.tsx
_components/card.tsx # not routable
api/
health/route.ts # "/api/health"// app/layout.tsx — the only required file, runs for every route
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}
// app/blog/[slug]/page.tsx — Next.js 15+: params is a Promise
export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params;
const post = await getPost(slug);
return <article>{post.title}</article>;
}
// app/blog/[slug]/template.tsx — remounts on every navigation under this segment
export default function Template({ children }: { children: React.ReactNode }) {
return <div className="fade-in">{children}</div>;
}
// app/api/health/route.ts — an endpoint, not a page
export async function GET() {
return Response.json({ ok: true, ts: Date.now() });
}// Route segment config: applies to this segment and its children
export const dynamic = "force-dynamic"; // or "auto" | "force-static" | "error"
export const revalidate = 60; // seconds; false = never
export const runtime = "nodejs"; // or "edge"
export const maxDuration = 30; // seconds (platform-dependent)
export const dynamicParams = true; // allow params outside generateStaticParamsKey Comparison Table
| File | Routable | Renders | Persists across navigation | Errors caught |
|---|---|---|---|---|
page.tsx | Yes | The route's content | No | By the nearest error.tsx |
layout.tsx | No | Shell wrapping children | Yes — state kept, does not re-render | No (falls to parent) |
template.tsx | No | Shell wrapping children | No — remounts each navigation | No |
loading.tsx | No | Suspense fallback for the segment | n/a | No |
error.tsx | No | Client error boundary UI | n/a | Yes, for its subtree |
global-error.tsx | No | Full-document boundary | n/a | Yes, including the root layout |
not-found.tsx | No | UI for notFound() | n/a | n/a |
route.ts | Yes (as an endpoint) | HTTP response | n/a | By you |
| Folder convention | URL effect | Purpose |
|---|---|---|
about/ | Adds /about | Ordinary segment |
[slug]/ | Adds /[slug] | Dynamic segment |
[...slug]/ | Adds catch-all | One or more segments |
[[...slug]]/ | Adds optional catch-all | Zero or more segments |
(group)/ | No change | Route group with its own layout |
_private/ | Excluded | Non-routable files and helpers |
@slot/ | No change | Parallel route slot |
(.)photo/ | No change | Intercepting route |
Practical Edge Cases & Deep Dives
1. Layout versus template: the state that survives navigation
A layout does not unmount when the route below it changes. A collapsible sidebar with useState in a layout keeps its state as you move from /dashboard to /dashboard/settings, and the layout is not re-rendered on that navigation. A template is the opposite: it is a new instance per navigation, so its state resets and an entrance animation replays.
// app/dashboard/layout.tsx — state survives; good for chrome
"use client";
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
const [open, setOpen] = useState(true); // preserved across /dashboard/*
return <aside data-open={open}>{children}</aside>;
}Use a template for page-transition animation, for useEffect that must run per navigation, or for a form whose state must not leak between records. Do not use a template to force a data refresh — revalidation is the tool for that, and a template does not reset server-side caches.
2. Layouts cannot read searchParams
// app/shop/layout.tsx
export default function ShopLayout({ searchParams }: { searchParams: { q?: string } }) {
// Never populated. Layouts do not receive searchParams.
return <div>{searchParams.q}</div>;
}The layout sits outside the page's dynamic boundary, so search parameters are not available there. Reading them in a client component with useSearchParams() works but opts the whole subtree out of static rendering unless it sits under a <Suspense> boundary. The usual fixes: move the parameter-dependent UI into the page, read it in a client component wrapped in Suspense, or use a template plus a client hook when the UI truly must be a shell above the page.
3. Route groups: two shells, one URL space
(marketing) and (app) let two different root-level layouts coexist — a marketing layout without a sidebar and an app layout with one — while keeping /about and /dashboard as ordinary URLs. Two constraints follow: a route may not resolve to two groups that both define a conflicting page.tsx at the same path (build error), and each group that defines its own <html> must be a root layout, which means the top-level app/layout.tsx must not exist if the groups own the document.
app/(marketing)/layout.tsx -> <html><body> for the marketing shell
app/(app)/layout.tsx -> <html><body> for the app shell
# both are root layouts because app/layout.tsx is absent4. loading.tsx is a Suspense boundary, and it replaces the whole segment
loading.tsx wraps the segment's page in a Suspense boundary and shows while the page's data resolves on the server. Two consequences: the fallback replaces the page, so a spinner that hides the page's layout should live in a nested loading.tsx rather than the top one; and a route with a very fast response still ships the fallback, causing a flash. For finer control, drop loading.tsx and place <Suspense fallback={...}> around the specific slow component — streaming then keeps the rest of the page interactive sooner.
export default async function Page() {
const slow = getSlowData(); // do not await yet
return (
<section>
<h1>Dashboard</h1>
<Suspense fallback={<TableSkeleton />}>
<Table data={slow} />
</Suspense>
</section>
);
}5. page.tsx and route.ts cannot share a segment
app/api/users/page.tsx -> page at /api/users
app/api/users/route.ts -> handler at /api/users
# both present: build error, conflicting route resolutionA segment is either a page or an endpoint. route.ts also cannot coexist with page.tsx in the same folder, and a route handler does not inherit layouts — it is an HTTP function, not a React tree. That is why an API folder nested under a layout-heavy path still returns plain JSON with no shell.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
| 404 for a folder that exists | No page.tsx or route.ts | Add the file; _ folders are private |
You should not have <html> in a nested layout | A layout below the root renders <html> | Only the root layout does |
| Layout state resets unexpectedly | A template.tsx is in the tree | Use layout.tsx for persistent state |
| Layout crashes and nothing catches it | error.tsx does not catch layout errors | Move the boundary up, or use global-error.tsx |
| Infinite redirect or blank page | A route group resolves two pages to one URL | Remove the duplicate path |
| Build error: conflicting route | page.tsx and route.ts in one folder | Split the segment |
searchParams undefined in a layout | Layouts do not receive them | Read them in the page or a client component |
| Static page becomes dynamic | cookies()/headers() used in the tree | Move it behind Suspense or accept dynamic rendering |
| Params typed as an object fail | Next.js 15+ uses Promises | await params in pages and handlers |
| Loading flash on fast routes | Top-level loading.tsx on a quick segment | Nest it, or use <Suspense> locally |
The convention files are the app's routing contract, and every one of them has an exact meaning: a layout persists, a template remounts, a page routes, a route answers HTTP, and a boundary catches. When a URL, a shell, or an error handler behaves unexpectedly, the answer is which file in that folder tree the framework actually chose.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesNext.js Static Export, Standalone Output, and Docker Deployment
Export has no server, standalone has a pruned one, and the default expects a full install. The three COPY lines that decide whether a container renders CSS.
Next.js Parallel Routes and Intercepting Routes: Slot Layouts and Modals
Named slots render several pages in one layout, and (.) interception makes a click open over the page while a direct link renders the full route. Why every slot needs default.tsx.
Next.js ISR: Route Revalidate, revalidateTag, and On-Demand Invalidation
Two clocks and one trigger: route revalidate seconds, fetch-level tags, and a webhook that calls revalidateTag. A timer is a ceiling on freshness, never a guarantee.
Next.js Environment Variables: NEXT_PUBLIC_, Build-Time Inlining, and Runtime Config
The prefix decides whether a value is compiled into the browser bundle or stays on the server. One image, two environments, and the choice that follows from it.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.