> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/next.js/llms.txt
> Use this file to discover all available pages before exploring further.
# Routing
> Learn how the App Router uses the file system to define routes — including dynamic routes, route groups, layouts, and middleware.
Next.js uses **file-system based routing**. Folders and files inside the `app` directory map directly to URL paths.
## File-system routing
The App Router defines routes using two conventions:
* **Folders** define the route segments that map to URL segments
* **Files** (`page.tsx`, `layout.tsx`, etc.) create UI that is shown for a segment
### Pages
A `page` file makes a route segment publicly accessible:
```tsx filename="app/page.tsx" theme={null}
export default function Page() {
return
Hello Next.js!
}
```
```
app/
├── page.tsx → /
├── blog/
│ ├── page.tsx → /blog
│ └── [slug]/
│ └── page.tsx → /blog/:slug
```
### Layouts
A `layout` file defines UI that is shared across multiple pages. Layouts preserve state, remain interactive, and do not re-render on navigation.
```tsx filename="app/layout.tsx" theme={null}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
{children}
)
}
```
The root layout at `app/layout.tsx` is required and must contain `` and `` tags.
### Nested layouts
Layouts are nested automatically. A layout at `app/blog/layout.tsx` wraps all pages inside `app/blog/`:
```tsx filename="app/blog/layout.tsx" theme={null}
export default function BlogLayout({
children,
}: {
children: React.ReactNode
}) {
return {children}
}
```
The rendering hierarchy becomes: `RootLayout → BlogLayout → Page`.
## Dynamic routes
Wrap a folder name in square brackets to create a dynamic segment:
```tsx filename="app/blog/[slug]/page.tsx" theme={null}
export default async function BlogPostPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const post = await getPost(slug)
return (
{post.title}
{post.content}
)
}
```
`params` is a Promise in the App Router. Always `await` it before accessing its values.
### Catch-all segments
Use `[...slug]` to match multiple segments:
```
app/docs/[...slug]/page.tsx → /docs/a, /docs/a/b, /docs/a/b/c
```
Use `[[...slug]]` (double brackets) for optional catch-all, which also matches the root `/docs`.
### generateStaticParams
Use `generateStaticParams` to statically generate dynamic routes at build time:
```tsx filename="app/blog/[slug]/page.tsx" theme={null}
export async function generateStaticParams() {
const posts = await getPosts()
return posts.map((post) => ({ slug: post.slug }))
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// ...
}
```
## Route groups
Wrap a folder name in parentheses to create a route group. Route groups organize routes without affecting the URL:
```
app/
├── (marketing)/
│ ├── layout.tsx ← applies only to this group
│ ├── page.tsx → /
│ └── about/
│ └── page.tsx → /about
└── (dashboard)/
├── layout.tsx ← different layout for dashboard
└── settings/
└── page.tsx → /settings
```
Route groups are useful for:
* Applying different layouts to different sections without changing URLs
* Organizing large codebases by feature or team
* Creating multiple root layouts
## Special files
The App Router has several reserved file names:
Makes a route segment publicly accessible. Receives `params` and `searchParams` props.
Shared UI that wraps child pages and layouts. Does not re-render on navigation.
Instant loading state shown while a route segment loads. Automatically wraps the segment in ``.
Error UI for a route segment. Must be a Client Component.
UI shown when `notFound()` is called inside a segment.
API endpoint for the segment. Equivalent to API Routes in the Pages Router.
## Search params
Access search parameters in a Server Component page via the `searchParams` prop:
```tsx filename="app/page.tsx" theme={null}
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
const filters = (await searchParams).filters
}
```
Using `searchParams` opts the page into dynamic rendering. In Client Components, use the `useSearchParams` hook instead.
## Navigation
Use the `` component for client-side navigation with automatic prefetching:
```tsx filename="app/layout.tsx" theme={null}
import Link from 'next/link'
export default function Layout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
`` automatically prefetches routes when they enter the viewport:
* **Static routes**: the full route is prefetched
* **Dynamic routes**: prefetching is skipped or partial if `loading.tsx` is present
### Programmatic navigation
Use `useRouter` in Client Components for programmatic navigation:
```tsx filename="app/ui/back-button.tsx" theme={null}
'use client'
import { useRouter } from 'next/navigation'
export default function BackButton() {
const router = useRouter()
return
}
```
## Route type helpers
Next.js generates utility types that infer `params` and named slots from your route structure:
```tsx filename="app/blog/[slug]/page.tsx" theme={null}
export default async function Page(props: PageProps<'/blog/[slug]'>) {
const { slug } = await props.params
return
Blog post: {slug}
}
```
```tsx filename="app/dashboard/layout.tsx" theme={null}
export default function Layout(props: LayoutProps<'/dashboard'>) {
return {props.children}
}
```
These types are globally available — no imports required. They're generated during `next dev`, `next build`, or `next typegen`.
## Middleware
Middleware runs before a request is completed and allows you to rewrite, redirect, or modify the request:
```typescript filename="middleware.ts" theme={null}
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
// Redirect unauthenticated users
if (!request.cookies.get('token')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
export const config = {
matcher: ['/dashboard/:path*'],
}
```
Place `middleware.ts` at the root of your project (same level as `app/`). The `matcher` config controls which paths trigger the middleware.
Middleware runs on every matched request. Keep it lightweight — avoid expensive operations like database queries.