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

error-handling.md

Syntax-highlighted preview of this file as included in the skill package.

Rendered Source

markdown228 linesFree

error-handling.md

1# Error Handling
2 
3Handle errors gracefully in Next.js applications.
4 
5Reference: https://nextjs.org/docs/app/getting-started/error-handling
6 
7## Error Boundaries
8 
9### `error.tsx`
10 
11Catches errors in a route segment and its children:
12 
13```tsx
14'use client'
15 
16export default function Error({
17  error,
18  reset,
19}: {
20  error: Error & { digest?: string }
21  reset: () => void
22}) {
23  return (
24    <div>
25      <h2>Something went wrong!</h2>
26      <button onClick={() => reset()}>Try again</button>
27    </div>
28  )
29}
30```
31 
32**Important:** `error.tsx` must be a Client Component.
33 
34### `global-error.tsx`
35 
36Catches errors in root layout:
37 
38```tsx
39'use client'
40 
41export default function GlobalError({
42  error,
43  reset,
44}: {
45  error: Error & { digest?: string }
46  reset: () => void
47}) {
48  return (
49    <html>
50      <body>
51        <h2>Something went wrong!</h2>
52        <button onClick={() => reset()}>Try again</button>
53      </body>
54    </html>
55  )
56}
57```
58 
59**Important:** Must include `<html>` and `<body>` tags.
60 
61## Server Actions: Navigation API Gotcha
62 
63**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
64 
65Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
66 
67```tsx
68'use server'
69 
70import { redirect } from 'next/navigation'
71import { notFound } from 'next/navigation'
72 
73// Bad: try-catch catches the navigation "error"
74async function createPost(formData: FormData) {
75  try {
76    const post = await db.post.create({ ... })
77    redirect(`/posts/${post.id}`)  // This throws!
78  } catch (error) {
79    // redirect() throw is caught here - navigation fails!
80    return { error: 'Failed to create post' }
81  }
82}
83 
84// Good: Call navigation APIs outside try-catch
85async function createPost(formData: FormData) {
86  let post
87  try {
88    post = await db.post.create({ ... })
89  } catch (error) {
90    return { error: 'Failed to create post' }
91  }
92  redirect(`/posts/${post.id}`)  // Outside try-catch
93}
94 
95// Good: Re-throw navigation errors
96async function createPost(formData: FormData) {
97  try {
98    const post = await db.post.create({ ... })
99    redirect(`/posts/${post.id}`)
100  } catch (error) {
101    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
102      throw error  // Re-throw navigation errors
103    }
104    return { error: 'Failed to create post' }
105  }
106}
107```
108 
109Same applies to:
110- `redirect()` - 307 temporary redirect
111- `permanentRedirect()` - 308 permanent redirect
112- `notFound()` - 404 not found
113- `forbidden()` - 403 forbidden
114- `unauthorized()` - 401 unauthorized
115 
116Use `unstable_rethrow()` to re-throw these errors in catch blocks:
117 
118```tsx
119import { unstable_rethrow } from 'next/navigation'
120 
121async function action() {
122  try {
123    // ...
124    redirect('/success')
125  } catch (error) {
126    unstable_rethrow(error) // Re-throws Next.js internal errors
127    return { error: 'Something went wrong' }
128  }
129}
130```
131 
132## Redirects
133 
134```tsx
135import { redirect, permanentRedirect } from 'next/navigation'
136 
137// 307 Temporary - use for most cases
138redirect('/new-path')
139 
140// 308 Permanent - use for URL migrations (cached by browsers)
141permanentRedirect('/new-url')
142```
143 
144## Auth Errors
145 
146Trigger auth-related error pages:
147 
148```tsx
149import { forbidden, unauthorized } from 'next/navigation'
150 
151async function Page() {
152  const session = await getSession()
153 
154  if (!session) {
155    unauthorized() // Renders unauthorized.tsx (401)
156  }
157 
158  if (!session.hasAccess) {
159    forbidden() // Renders forbidden.tsx (403)
160  }
161 
162  return <Dashboard />
163}
164```
165 
166Create corresponding error pages:
167 
168```tsx
169// app/forbidden.tsx
170export default function Forbidden() {
171  return <div>You don't have access to this resource</div>
172}
173 
174// app/unauthorized.tsx
175export default function Unauthorized() {
176  return <div>Please log in to continue</div>
177}
178```
179 
180## Not Found
181 
182### `not-found.tsx`
183 
184Custom 404 page for a route segment:
185 
186```tsx
187export default function NotFound() {
188  return (
189    <div>
190      <h2>Not Found</h2>
191      <p>Could not find the requested resource</p>
192    </div>
193  )
194}
195```
196 
197### Triggering Not Found
198 
199```tsx
200import { notFound } from 'next/navigation'
201 
202export default async function Page({ params }: { params: Promise<{ id: string }> }) {
203  const { id } = await params
204  const post = await getPost(id)
205 
206  if (!post) {
207    notFound()  // Renders closest not-found.tsx
208  }
209 
210  return <div>{post.title}</div>
211}
212```
213 
214## Error Hierarchy
215 
216Errors bubble up to the nearest error boundary:
217 
218```
219app/
220├── error.tsx           # Catches errors from all children
221├── blog/
222│   ├── error.tsx       # Catches errors in /blog/*
223│   └── [slug]/
224│       ├── error.tsx   # Catches errors in /blog/[slug]
225│       └── page.tsx
226└── layout.tsx          # Errors here go to global-error.tsx
227```
228

Marketplace

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

error-handling.md

Syntax-highlighted preview of this file as included in the skill package.

Rendered Source

markdown228 linesFree

error-handling.md

1# Error Handling
2 
3Handle errors gracefully in Next.js applications.
4 
5Reference: https://nextjs.org/docs/app/getting-started/error-handling
6 
7## Error Boundaries
8 
9### `error.tsx`
10 
11Catches errors in a route segment and its children:
12 
13```tsx
14'use client'
15 
16export default function Error({
17  error,
18  reset,
19}: {
20  error: Error & { digest?: string }
21  reset: () => void
22}) {
23  return (
24    <div>
25      <h2>Something went wrong!</h2>
26      <button onClick={() => reset()}>Try again</button>
27    </div>
28  )
29}
30```
31 
32**Important:** `error.tsx` must be a Client Component.
33 
34### `global-error.tsx`
35 
36Catches errors in root layout:
37 
38```tsx
39'use client'
40 
41export default function GlobalError({
42  error,
43  reset,
44}: {
45  error: Error & { digest?: string }
46  reset: () => void
47}) {
48  return (
49    <html>
50      <body>
51        <h2>Something went wrong!</h2>
52        <button onClick={() => reset()}>Try again</button>
53      </body>
54    </html>
55  )
56}
57```
58 
59**Important:** Must include `<html>` and `<body>` tags.
60 
61## Server Actions: Navigation API Gotcha
62 
63**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
64 
65Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
66 
67```tsx
68'use server'
69 
70import { redirect } from 'next/navigation'
71import { notFound } from 'next/navigation'
72 
73// Bad: try-catch catches the navigation "error"
74async function createPost(formData: FormData) {
75  try {
76    const post = await db.post.create({ ... })
77    redirect(`/posts/${post.id}`)  // This throws!
78  } catch (error) {
79    // redirect() throw is caught here - navigation fails!
80    return { error: 'Failed to create post' }
81  }
82}
83 
84// Good: Call navigation APIs outside try-catch
85async function createPost(formData: FormData) {
86  let post
87  try {
88    post = await db.post.create({ ... })
89  } catch (error) {
90    return { error: 'Failed to create post' }
91  }
92  redirect(`/posts/${post.id}`)  // Outside try-catch
93}
94 
95// Good: Re-throw navigation errors
96async function createPost(formData: FormData) {
97  try {
98    const post = await db.post.create({ ... })
99    redirect(`/posts/${post.id}`)
100  } catch (error) {
101    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
102      throw error  // Re-throw navigation errors
103    }
104    return { error: 'Failed to create post' }
105  }
106}
107```
108 
109Same applies to:
110- `redirect()` - 307 temporary redirect
111- `permanentRedirect()` - 308 permanent redirect
112- `notFound()` - 404 not found
113- `forbidden()` - 403 forbidden
114- `unauthorized()` - 401 unauthorized
115 
116Use `unstable_rethrow()` to re-throw these errors in catch blocks:
117 
118```tsx
119import { unstable_rethrow } from 'next/navigation'
120 
121async function action() {
122  try {
123    // ...
124    redirect('/success')
125  } catch (error) {
126    unstable_rethrow(error) // Re-throws Next.js internal errors
127    return { error: 'Something went wrong' }
128  }
129}
130```
131 
132## Redirects
133 
134```tsx
135import { redirect, permanentRedirect } from 'next/navigation'
136 
137// 307 Temporary - use for most cases
138redirect('/new-path')
139 
140// 308 Permanent - use for URL migrations (cached by browsers)
141permanentRedirect('/new-url')
142```
143 
144## Auth Errors
145 
146Trigger auth-related error pages:
147 
148```tsx
149import { forbidden, unauthorized } from 'next/navigation'
150 
151async function Page() {
152  const session = await getSession()
153 
154  if (!session) {
155    unauthorized() // Renders unauthorized.tsx (401)
156  }
157 
158  if (!session.hasAccess) {
159    forbidden() // Renders forbidden.tsx (403)
160  }
161 
162  return <Dashboard />
163}
164```
165 
166Create corresponding error pages:
167 
168```tsx
169// app/forbidden.tsx
170export default function Forbidden() {
171  return <div>You don't have access to this resource</div>
172}
173 
174// app/unauthorized.tsx
175export default function Unauthorized() {
176  return <div>Please log in to continue</div>
177}
178```
179 
180## Not Found
181 
182### `not-found.tsx`
183 
184Custom 404 page for a route segment:
185 
186```tsx
187export default function NotFound() {
188  return (
189    <div>
190      <h2>Not Found</h2>
191      <p>Could not find the requested resource</p>
192    </div>
193  )
194}
195```
196 
197### Triggering Not Found
198 
199```tsx
200import { notFound } from 'next/navigation'
201 
202export default async function Page({ params }: { params: Promise<{ id: string }> }) {
203  const { id } = await params
204  const post = await getPost(id)
205 
206  if (!post) {
207    notFound()  // Renders closest not-found.tsx
208  }
209 
210  return <div>{post.title}</div>
211}
212```
213 
214## Error Hierarchy
215 
216Errors bubble up to the nearest error boundary:
217 
218```
219app/
220├── error.tsx           # Catches errors from all children
221├── blog/
222│   ├── error.tsx       # Catches errors in /blog/*
223│   └── [slug]/
224│       ├── error.tsx   # Catches errors in /blog/[slug]
225│       └── page.tsx
226└── layout.tsx          # Errors here go to global-error.tsx
227```
228

Next.js Best Practices

error-handling.md

Preparing the source view

Next.js Best Practices

error-handling.md