Next.js Routing Best Practices

A condensed summary of the 25 most important best practices drawn from every page in this section.

Await params and searchParams: In Next.js 15+ both props are Promises in Server Components - const { id } = await params - destructuring without await yields the Promise object and your lookups silently return undefined.
Don't Collide page.tsx With route.tsx: A folder cannot contain both a page.tsx and a route.tsx - the Route Handler will shadow the page, so keep API routes under app/api/ to avoid silent conflicts.
Use template.tsx for Per-Nav Resets: layout.tsx persists across navigation and its state survives child route changes; when you specifically need to remount (e.g., reset animations or state on each nav), use template.tsx instead.
Parse Dynamic Param Types: Every dynamic segment value arrives as a string - const postId = Number(params.id) - so coerce to the shape you actually need instead of trusting the type annotation alone.
Use [[...slug]] When the Base Path Must Match: A catch-all [...path] does not match the parent route, so /docs 404s; switch to [[...path]] or add a separate page.tsx alongside it when the base segment should resolve.
Let Static Beat Dynamic Explicitly: When static and dynamic routes overlap, the static one always wins, so you can keep a /blog/about/page.tsx next to [slug]/page.tsx without conflict.
generateStaticParams Runs at Build Time: The function executes during next build, so any unavailable data source fails the build; pair it with dynamicParams = true when new paths should still render on first request.
error.tsx Must Be "use client": React Error Boundaries require client lifecycle, so every error.tsx needs the "use client" directive - and it only catches errors below itself, never in the sibling layout.tsx at the same segment.
global-error.tsx Owns html and body: global-error.tsx replaces the entire root layout when it triggers, so it must render its own <html><body>; also note it only activates in production (the dev overlay runs in development).
notFound and redirect Throw: Both throw Next.js sentinel errors, so a surrounding try/catch swallows them - call them outside try/catch, or use unstable_rethrow in the catch block to let them propagate.
Reserve Root not-found for Unmatched Routes: The root not-found.tsx auto-catches any URL that does not match a route, while nested not-found.tsx files only fire when you explicitly call notFound() from within that subtree.
Layouts Can't Read searchParams: Only pages receive searchParams; if a layout needs URL state, lift the logic into a page or a Client Component that uses useSearchParams() inside a Suspense boundary.
Pass Data Via Context, Not Layout Props: Layouts cannot forward props to their children, so share state through a Client Context provider, cookies, or a Server Component helper that re-fetches in each child.
Import useRouter From next/navigation: In the App Router, useRouter, usePathname, and useSearchParams live in next/navigation; next/router is the Pages Router and silently fails or 404s when imported.
Wrap useSearchParams in Suspense: useSearchParams() without a surrounding <Suspense> boundary opts the whole route into client-side rendering - always gate it: <Suspense fallback={null}><SearchFilters /></Suspense>.
Use useTransition for Pending UI: router.push() returns void, so wrap navigations in useTransition - startTransition(() => router.push("/dashboard")) - to get an isPending flag and disable buttons or show spinners during route changes.
router.refresh Scoped to Current Route: refresh() re-fetches server data for the active route only; other cached routes stay stale, so pair it with revalidateTag/revalidatePath when the mutation affects siblings.
Control Link Prefetch and Scroll: <Link> prefetches on viewport entry and scrolls to top by default - <Link href="/settings" prefetch={false} scroll={false}> - set prefetch={false} on rarely used links and scroll={false} for tab/filter UIs that should stay in place.
Always Set a Middleware matcher: Without config.matcher your middleware runs on every request including /_next/static and favicons - export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } - scope it explicitly and exclude redirect destinations to avoid infinite loops.
Edge Middleware Forbids Node APIs: Middleware runs in the Edge Runtime, so bcrypt, fs, and most database drivers break at build or runtime - use Web APIs and edge-compatible libraries only.
Return NextResponse.next to Continue: NextResponse.next() does not short-circuit; you must return it (or a redirect/rewrite) to actually stop the middleware chain, otherwise subsequent logic keeps executing.
Every Parallel Slot Needs default.tsx: @slot folders must include a default.tsx fallback, otherwise hard navigations or mismatched subroutes 404; slots must also be direct children of the layout and cannot nest inside each other.
Reserve Space for Independent Slots: Parallel route slots resolve independently, so give each one a fixed height or skeleton matching the final content - otherwise streaming causes visible layout shift as each slot fills in.
Mind the Intercepting Dot Convention: (.), (..), (..)(..), and (...) count route-group segments the same as regular folders, so route groups may require an extra (..) hop; missing default.tsx in the hosting slot also breaks back-navigation dismiss.
Route Groups Cannot Collide: Two (group) folders cannot resolve to the same URL path (the build fails), and multiple root layouts force a full page reload between groups instead of soft navigation - keep the home route / in exactly one group.

Await params and searchParams: In Next.js 15+ both props are Promises in Server Components - const { id } = await params - destructuring without await yields the Promise object and your lookups silently return undefined.
Don't Collide page.tsx With route.tsx: A folder cannot contain both a page.tsx and a route.tsx - the Route Handler will shadow the page, so keep API routes under app/api/ to avoid silent conflicts.
Use template.tsx for Per-Nav Resets: layout.tsx persists across navigation and its state survives child route changes; when you specifically need to remount (e.g., reset animations or state on each nav), use template.tsx instead.
Parse Dynamic Param Types: Every dynamic segment value arrives as a string - const postId = Number(params.id) - so coerce to the shape you actually need instead of trusting the type annotation alone.
Use [[...slug]] When the Base Path Must Match: A catch-all [...path] does not match the parent route, so /docs 404s; switch to [[...path]] or add a separate page.tsx alongside it when the base segment should resolve.
Let Static Beat Dynamic Explicitly: When static and dynamic routes overlap, the static one always wins, so you can keep a /blog/about/page.tsx next to [slug]/page.tsx without conflict.
generateStaticParams Runs at Build Time: The function executes during next build, so any unavailable data source fails the build; pair it with dynamicParams = true when new paths should still render on first request.
error.tsx Must Be "use client": React Error Boundaries require client lifecycle, so every error.tsx needs the "use client" directive - and it only catches errors below itself, never in the sibling layout.tsx at the same segment.
global-error.tsx Owns html and body: global-error.tsx replaces the entire root layout when it triggers, so it must render its own <html><body>; also note it only activates in production (the dev overlay runs in development).
notFound and redirect Throw: Both throw Next.js sentinel errors, so a surrounding try/catch swallows them - call them outside try/catch, or use unstable_rethrow in the catch block to let them propagate.
Reserve Root not-found for Unmatched Routes: The root not-found.tsx auto-catches any URL that does not match a route, while nested not-found.tsx files only fire when you explicitly call notFound() from within that subtree.
Layouts Can't Read searchParams: Only pages receive searchParams; if a layout needs URL state, lift the logic into a page or a Client Component that uses useSearchParams() inside a Suspense boundary.
Pass Data Via Context, Not Layout Props: Layouts cannot forward props to their children, so share state through a Client Context provider, cookies, or a Server Component helper that re-fetches in each child.
Import useRouter From next/navigation: In the App Router, useRouter, usePathname, and useSearchParams live in next/navigation; next/router is the Pages Router and silently fails or 404s when imported.
Wrap useSearchParams in Suspense: useSearchParams() without a surrounding <Suspense> boundary opts the whole route into client-side rendering - always gate it: <Suspense fallback={null}><SearchFilters /></Suspense>.
Use useTransition for Pending UI: router.push() returns void, so wrap navigations in useTransition - startTransition(() => router.push("/dashboard")) - to get an isPending flag and disable buttons or show spinners during route changes.
router.refresh Scoped to Current Route: refresh() re-fetches server data for the active route only; other cached routes stay stale, so pair it with revalidateTag/revalidatePath when the mutation affects siblings.
Control Link Prefetch and Scroll: <Link> prefetches on viewport entry and scrolls to top by default - <Link href="/settings" prefetch={false} scroll={false}> - set prefetch={false} on rarely used links and scroll={false} for tab/filter UIs that should stay in place.
Always Set a Middleware matcher: Without config.matcher your middleware runs on every request including /_next/static and favicons - export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } - scope it explicitly and exclude redirect destinations to avoid infinite loops.
Edge Middleware Forbids Node APIs: Middleware runs in the Edge Runtime, so bcrypt, fs, and most database drivers break at build or runtime - use Web APIs and edge-compatible libraries only.
Return NextResponse.next to Continue: NextResponse.next() does not short-circuit; you must return it (or a redirect/rewrite) to actually stop the middleware chain, otherwise subsequent logic keeps executing.
Every Parallel Slot Needs default.tsx: @slot folders must include a default.tsx fallback, otherwise hard navigations or mismatched subroutes 404; slots must also be direct children of the layout and cannot nest inside each other.
Reserve Space for Independent Slots: Parallel route slots resolve independently, so give each one a fixed height or skeleton matching the final content - otherwise streaming causes visible layout shift as each slot fills in.
Mind the Intercepting Dot Convention: (.), (..), (..)(..), and (...) count route-group segments the same as regular folders, so route groups may require an extra (..) hop; missing default.tsx in the hosting slot also breaks back-navigation dismiss.
Route Groups Cannot Collide: Two (group) folders cannot resolve to the same URL path (the build fails), and multiple root layouts force a full page reload between groups instead of soft navigation - keep the home route / in exactly one group.

Next.js Routing Best Practices

Search Documentation

Next.js Routing Best Practices