Source from repo
Next.js Best Practices

Apply Next.js best practices for RSC boundaries, async APIs, routing, metadata, and optimization.
vercel-labsGitHub vercel-labsOfficialSource repo Original GitHub link Publisher page
Files
Skill
n/a
Size
78.7 KB
Entrypoint
SKILL.md
Format
git-repo
Open file
parallel-routes.md

Syntax-highlighted preview of this file as included in the skill package.
Rendered Source
markdown288 linesFree
parallel-routes.md
1# Parallel & Intercepting Routes
2 
3Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
4 
5## File Structure
6 
7```
8app/
9├── @modal/                    # Parallel route slot
10│   ├── default.tsx            # Required! Returns null
11│   ├── (.)photos/             # Intercepts /photos/*
12│   │   └── [id]/
13│   │       └── page.tsx       # Modal content
14│   └── [...]catchall/         # Optional: catch unmatched
15│       └── page.tsx
16├── photos/
17│   └── [id]/
18│       └── page.tsx           # Full page (direct access)
19├── layout.tsx                 # Renders both children and @modal
20└── page.tsx
21```
22 
23## Step 1: Root Layout with Slot
24 
25```tsx
26// app/layout.tsx
27export default function RootLayout({
28  children,
29  modal,
30}: {
31  children: React.ReactNode;
32  modal: React.ReactNode;
33}) {
34  return (
35    <html>
36      <body>
37        {children}
38        {modal}
39      </body>
40    </html>
41  );
42}
43```
44 
45## Step 2: Default File (Critical!)
46 
47**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
48 
49```tsx
50// app/@modal/default.tsx
51export default function Default() {
52  return null;
53}
54```
55 
56Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
57 
58## Step 3: Intercepting Route (Modal)
59 
60The `(.)` prefix intercepts routes at the same level.
61 
62```tsx
63// app/@modal/(.)photos/[id]/page.tsx
64import { Modal } from '@/components/modal';
65 
66export default async function PhotoModal({
67  params
68}: {
69  params: Promise<{ id: string }>
70}) {
71  const { id } = await params;
72  const photo = await getPhoto(id);
73 
74  return (
75    <Modal>
76      <img src={photo.url} alt={photo.title} />
77    </Modal>
78  );
79}
80```
81 
82## Step 4: Full Page (Direct Access)
83 
84```tsx
85// app/photos/[id]/page.tsx
86export default async function PhotoPage({
87  params
88}: {
89  params: Promise<{ id: string }>
90}) {
91  const { id } = await params;
92  const photo = await getPhoto(id);
93 
94  return (
95    <div className="full-page">
96      <img src={photo.url} alt={photo.title} />
97      <h1>{photo.title}</h1>
98    </div>
99  );
100}
101```
102 
103## Step 5: Modal Component with Correct Closing
104 
105**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
106 
107```tsx
108// components/modal.tsx
109'use client';
110 
111import { useRouter } from 'next/navigation';
112import { useCallback, useEffect, useRef } from 'react';
113 
114export function Modal({ children }: { children: React.ReactNode }) {
115  const router = useRouter();
116  const overlayRef = useRef<HTMLDivElement>(null);
117 
118  // Close on escape key
119  useEffect(() => {
120    function onKeyDown(e: KeyboardEvent) {
121      if (e.key === 'Escape') {
122        router.back(); // Correct
123      }
124    }
125    document.addEventListener('keydown', onKeyDown);
126    return () => document.removeEventListener('keydown', onKeyDown);
127  }, [router]);
128 
129  // Close on overlay click
130  const handleOverlayClick = useCallback((e: React.MouseEvent) => {
131    if (e.target === overlayRef.current) {
132      router.back(); // Correct
133    }
134  }, [router]);
135 
136  return (
137    <div
138      ref={overlayRef}
139      onClick={handleOverlayClick}
140      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
141    >
142      <div className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
143        <button
144          onClick={() => router.back()} // Correct!
145          className="absolute top-4 right-4"
146        >
147          Close
148        </button>
149        {children}
150      </div>
151    </div>
152  );
153}
154```
155 
156### Why NOT `router.push('/')` or `<Link href="/">`?
157 
158Using `push` or `Link` to "close" a modal:
1591. Adds a new history entry (back button shows modal again)
1602. Doesn't properly clear the intercepted route
1613. Can cause the modal to flash or persist unexpectedly
162 
163`router.back()` correctly:
1641. Removes the intercepted route from history
1652. Returns to the previous page
1663. Properly unmounts the modal
167 
168## Route Matcher Reference
169 
170Matchers match **route segments**, not filesystem paths:
171 
172| Matcher | Matches | Example |
173|---------|---------|---------|
174| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
175| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
176| `(..)(..)` | Two levels up | Rarely used |
177| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
178 
179**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
180 
181## Handling Hard Navigation
182 
183When users directly visit `/photos/123` (bookmark, refresh, shared link):
184- The intercepting route is bypassed
185- The full `photos/[id]/page.tsx` renders
186- Modal doesn't appear (expected behavior)
187 
188If you want the modal to appear on direct access too, you need additional logic:
189 
190```tsx
191// app/photos/[id]/page.tsx
192import { Modal } from '@/components/modal';
193 
194export default async function PhotoPage({ params }) {
195  const { id } = await params;
196  const photo = await getPhoto(id);
197 
198  // Option: Render as modal on direct access too
199  return (
200    <Modal>
201      <img src={photo.url} alt={photo.title} />
202    </Modal>
203  );
204}
205```
206 
207## Common Gotchas
208 
209### 1. Missing `default.tsx` → 404 on Refresh
210 
211Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
212 
213### 2. Modal Persists After Navigation
214 
215You're using `router.push()` instead of `router.back()`.
216 
217### 3. Nested Parallel Routes Need Defaults Too
218 
219If you have `@modal` inside a route group, each level needs its own `default.tsx`:
220 
221```
222app/
223├── (marketing)/
224│   ├── @modal/
225│   │   └── default.tsx     # Needed!
226│   └── layout.tsx
227└── layout.tsx
228```
229 
230### 4. Intercepted Route Shows Wrong Content
231 
232Check your matcher:
233- `(.)photos` intercepts `/photos` from the same route level
234- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
235 
236### 5. TypeScript Errors with `params`
237 
238In Next.js 15+, `params` is a Promise:
239 
240```tsx
241// Correct
242export default async function Page({ params }: { params: Promise<{ id: string }> }) {
243  const { id } = await params;
244}
245```
246 
247## Complete Example: Photo Gallery Modal
248 
249```
250app/
251├── @modal/
252│   ├── default.tsx
253│   └── (.)photos/
254│       └── [id]/
255│           └── page.tsx
256├── photos/
257│   ├── page.tsx           # Gallery grid
258│   └── [id]/
259│       └── page.tsx       # Full photo page
260├── layout.tsx
261└── page.tsx
262```
263 
264Links in the gallery:
265 
266```tsx
267// app/photos/page.tsx
268import Link from 'next/link';
269 
270export default async function Gallery() {
271  const photos = await getPhotos();
272 
273  return (
274    <div className="grid grid-cols-3 gap-4">
275      {photos.map(photo => (
276        <Link key={photo.id} href={`/photos/${photo.id}`}>
277          <img src={photo.thumbnail} alt={photo.title} />
278        </Link>
279      ))}
280    </div>
281  );
282}
283```
284 
285Clicking a photo → Modal opens (intercepted)
286Direct URL → Full page renders
287Refresh while modal open → Full page renders
288
Preparing the source view

Next.js Best Practices

parallel-routes.md
