404
+ ++ Sorry, the page you're looking for doesn't exist. +
+ + + Go back home + +
+```
+
+#### `components/`
+
+A common place to store reusable UI components.
+
+Example:
+
+```text
+components/
+ Navbar.tsx
+ Footer.tsx
+ Button.tsx
+```
+
+#### `lib/`
+
+Many developers use this folder for shared utilities such as:
+
+- API clients
+- Database functions
+- Helper functions
+- Validation schemas
+
+#### `next.config.ts`
+
+Contains project-specific Next.js configuration.
+
+### creating your first Next.js page
+
+Create the following page inside `app/page.tsx`:
+
+```tsx
+export default function Home() {
+ return + Sorry, the page you're looking for doesn't exist. +
+ + + Go back home + +User not found
; +} +``` + +The URL still returns a successful page (HTTP 200), which isn't ideal for SEO or APIs. + +#### After + +```tsx +import { notFound } from "next/navigation"; + +if (!user) { + notFound(); +} +``` + +Next.js returns the correct **404 HTTP status** while displaying your custom 404 page. + +This improves: + +- SEO +- User experience +- Search engine indexing +- Proper HTTP semantics + +## Tradeoffs + +- **When this shines:** Building production applications where users may request invalid routes or missing resources. +- **When to avoid it:** Don't use `notFound()` for permission or authentication errors. Those should return an authorization page or redirect users to sign in. +- **What you give up:** Calling `notFound()` immediately stops rendering the current page, so no additional code after it will execute. + +## Key Takeaways + +- Next.js automatically provides a 404 page for routes that don't exist. +- Create `app/not-found.tsx` to customize the global 404 page. +- Use `notFound()` from `next/navigation` when requested data cannot be found. +- Route segments can have their own `not-found.tsx` files for customized experiences. +- Using `notFound()` returns the proper HTTP 404 status, improving SEO and user experience. + +## References + +- [api-reference/file-conventions/not-found](https://nextjs.org/docs/app/api-reference/file-conventions/not-found) +- [api-reference/functions/not-found](https://nextjs.org/docs/app/api-reference/functions/not-found) diff --git a/next/error-handling-in-nextjs.md b/next/error-handling-in-nextjs.md new file mode 100644 index 0000000..684646c --- /dev/null +++ b/next/error-handling-in-nextjs.md @@ -0,0 +1,292 @@ +# Error Handling in Next.js + +> **Topic:** Next.js · **Level:** Beginner · **Author:** [@geliettech](https://github.com/geliettech) + +## The Problem + +Applications don't always work as expected. + +A network request may fail, a database query may throw an exception, a component may crash because of unexpected data, or a third-party service may become unavailable. + +Without proper error handling: + +- Users see a blank page or an unhelpful browser error. +- A single broken component can crash an entire page. +- Developers have little information for debugging. +- Users cannot recover without manually refreshing the page. + +In traditional React applications, developers typically create **Error Boundaries** manually to catch rendering errors. While this works, it requires extra configuration and careful placement throughout the application. + +Next.js simplifies this process by providing **file-based error handling**. By creating special files such as `error.tsx` and `global-error.tsx`, you can display friendly error pages, isolate failures to specific route segments, and even allow users to recover without leaving the page. + +## The Solution + +The App Router provides built-in support for handling errors at different levels of your application. + +There are three primary ways to handle errors: + +- Recovering from route errors using `error.tsx` +- Handling errors in nested routes +- Handling application-wide failures with `global-error.tsx` + +### Recovering from Errors + +To handle errors for a specific route segment, create an `error.tsx` file inside that route. + +``` +app +│── dashboard +│ ├── page.tsx +│ ├── error.tsx +│ └── loading.tsx +``` + +When an error occurs inside `dashboard/page.tsx` or any of its child components, Next.js automatically renders `error.tsx` instead of crashing the entire application. + +#### Example + +```tsx +// app/dashboard/error.tsx + +"use client"; + +export default function Error({ + error, + reset, +}: { + error: Error; + reset: () => void; +}) { + return ( +{error.message}
+ + +{error.message}
+ + + + + ); +} +``` + +Notice that the component returns both: + +```tsx + + ... + +``` + +Since this component replaces the entire application, it must render the root HTML elements. + +--- + +### Throwing an Error + +Errors can be thrown manually. + +```tsx +export default async function Dashboard() { + throw new Error("Failed to load dashboard"); + + returnLoading dashboard...
; +} +``` + +Your page can then fetch data normally. + +```tsx +// app/dashboard/page.tsx + +async function getUsers() { + const res = await fetch("https://jsonplaceholder.typicode.com/users"); + + return res.json(); +} + +export default async function DashboardPage() { + const users = await getUsers(); + + return ( +{user.name}
+ ))} +{product}
+ + ); +} +``` + +### catach-all segements + +Sometimes you don't know how many URL segments you'll receive. + +Use `[...]`. + +``` +app/ +└── docs/ + └── [...slug]/ + └── page.tsx +``` + +Examples: + +``` +/docs/react +/docs/react/hooks +/docs/react/hooks/use-effect +``` + +```tsx +type Props = { + params: Promise<{ + slug: string[]; + }>; +}; + +export default async function DocsPage({ params }: Props) { + const { slug } = await params; + + return{slug.join(" / ")}
; +} +``` + +#### Optional Catch-all + +If the route should also match `/docs`, use: + +``` +[[...slug]] +``` + +This matches: + +``` +/docs +/docs/react +/docs/react/hooks +``` + +### Route Groups + +Sometimes folders are only used for organization and shouldn't appear in the URL. + +Wrap the folder name in parentheses. + +``` +app/ +├── (marketing)/ +│ ├── about/ +│ └── pricing/ +└── (dashboard)/ + └── settings/ +``` + +Generated URLs: + +``` +/about +/pricing +/settings +``` + +Notice `(marketing)` and `(dashboard)` are omitted from the URL. + +Route groups are useful for: + +- Organizing large projects +- Using different layouts +- Separating public and authenticated sections + +### Link Component + +Instead of using HTML `` tags for internal navigation, use Next.js' `Link` component. + +```tsx +import Link from "next/link"; + +export default function Navbar() { + return ( + + ); +} +``` + +Benefits include: + +- Client-side navigation +- Faster page transitions +- Automatic prefetching of linked pages (when links enter the viewport in production) + +### Active Links + +You can determine the current route using `usePathname()`. + +```tsx +"use client"; + +import Link from "next/link"; +import { usePathname } from "next/navigation"; + +export default function Navbar() { + const pathname = usePathname(); + + return ( + + ); +} +``` + +This is commonly used to highlight the active navigation item. + +### Params & Search Params + +#### Route Params + +Dynamic route values come from `params`. + +``` +/blog/nextjs-routing +``` + +```tsx +type Props = { + params: Promise<{ + slug: string; + }>; +}; + +export default async function Page({ params }: Props) { + const { slug } = await params; + + returnCategory: {category}
+Page: {page}
+ + ); +} +``` + +For Client Components, use the `useSearchParams()` hook. + +### Navigating Programmatically + +Sometimes navigation happens after an action, such as: + +- Form submission +- Login +- Logout +- Creating a resource + +Use the `useRouter()` hook. + +```tsx +"use client"; + +import { useRouter } from "next/navigation"; + +export default function LoginButton() { + const router = useRouter(); + + function handleLogin() { + // authenticate user... + + router.push("/dashboard"); + } + + return ; +} +``` + +Useful router methods include: + +```tsx +router.push("/dashboard"); // Navigate to a new page +router.replace("/login"); // Replace current history entry +router.back(); // Go back +router.forward(); // Go forward +router.refresh(); // Refresh server components +router.prefetch("/dashboard"); // Prefetch a route +``` + +### Before vs After + +#### Before (React Router) + +```tsx +import { BrowserRouter, Routes, Route } from "react-router-dom"; + +