struxadotcloud/struxa

public

initial commitd4cb9e15 months ago228 lines · 4.7 KB

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