Handling Runtime Errors

Next.js utilizes the error.tsx file convention to gracefully manage unexpected runtime errors within nested routes. This mechanism isolates the error to the specific segment where it occurred, allowing the remainder of the application to remain functional.

It is important to note that an error.tsx file cannot catch errors originating from its sibling layout.tsx file. To handle layout errors, the error boundary must be placed in a parent level. For catching errors in the root layout specifically, Next.js provides global-error.tsx.

The global-error.tsx file has specific requirements:

• It must be defined as a Client Component using the 'use client' directive.
• It must include its own <html> and <body> tags, as it effectively replaces the root layout when active.

Implementation Example:

Consider an error boundary defined for a dashboard route.

// app/dashboard/error.tsx
'use client'

interface ErrorProps {
  error: Error;
  reset: () => void;
}

export default function ErrorFallback({ error, reset }: ErrorProps) {
  return (
    <div className="p-4 border border-red-500 bg-red-50">
      <h2 className="text-lg font-bold text-red-800">An error occurred!</h2>
      <p className="text-red-600">{error.message}</p>
      <button 
        onClick={() => reset()}
        className="mt-4 px-4 py-2 bg-red-600 text-white rounded"
      >
        Attempt Recovery
      </button>
    </div>
  );
}

The corresponding page component can simulate an error to test the boundary.

// app/dashboard/page.tsx
export default function DashboardPage() {
  // Simulating a runtime error
  throw new Error('Failed to load dashboard data');

  return <div>Dashboard Content</div>;
}

Implementing Parallel Routes

Parallel routes allow for the simultaneous rendering of multiple pages within the same layout. This is achieved using "slots," defined by folders named with the @ prefix (e.g., @team). These slot folders are not added to the URL path.

Key use cases include:

• Rendering multiple views conditionally or simultaneously in a complex layout.
• Handling specific states like 404s independently for different slots.
• Defining separate loading.tsx and error.tsx files for each route segment.

Layout Configuration:

Slots are passed as props to the parent layout. For instance, a layout rendering @analytics and @team slots would look like this:

// app/layout.tsx
import { ReactNode } from 'react';

export default function RootLayout({
  children,
  analytics,
  team,
}: {
  children: ReactNode;
  analytics: ReactNode;
  team: ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <div className="container">
          <div className="main-content">{children}</div>
          <aside className="sidebar">
            {analytics}
            {team}
          </aside>
        </div>
      </body>
    </html>
  );
}

Handling 404s During Hard Navigation

A common pitfall with parallel routes occurs during page refreshes (hard navigation). If a user navigates to /team via a client-side link (soft navigation), only the content in the @team slot updates. However, upon refreshing the page, Next.js attempts to find a page.tsx matching the current URL (team) inside all defined slots (@team, @analytics, and the default children).

If the route is missing in any of these slots, the application throws a 404 error.

To resolve this without creating redundant page files for every slot, Next.js provides the default.tsx file. Placing a default.tsx inside a slot folder (e.g., app/@analytics/default.tsx) serves as a fallback when Next.js cannot retrieve the active route for that slot.