Next.js 13.4 Error Handling Guide for App Router

This article will explain how to use the new error file convention to handle errors in App Router in Next.js.

Error handling is a key aspect of any web application development. In the past, Next.js helped developers handle errors by customizing error pages such as 404 and 500 pages. However, these pages have limitations in Pages Router, such as limited support for specific UI integrations, outdated support for React error boundaries, and limited application functionality when an error occurs.

After the release of Next.js version 13.4, the new App Router has been officially put into production. App Router enhances support and developer experience for error handling and other basic parts of web application building.

Key Points

• Next.js version 13.4 introduces App Router, which enhances support and developer experience for error handling and other important parts of your web application.
The
• app file in the error.tsx directory creates a React error boundary to prevent the application from crashing when an error occurs. It can also act as a fallback component, rendering when an error is thrown within the boundary.
• Custom exceptions can be created to abstract error messages across multiple routes in your application. For example, you can use a custom AuthRequiredError to handle authentication errors in various routes.
• Errors can occur anywhere in the Next.js application. They will bubble to the nearest parent error boundary. For root layout or template errors, the global-error.tsx file should be used. If an error occurs in the server component or during data acquisition, Next.js forwards the corresponding Error object to the nearest error.tsx boundary.

Scenes and Settings

To facilitate understanding of the new error handling API, we will explore its implementation in Next.js user authentication application.

User authentication is prone to many errors, so when building other applications, it will be of great benefit to learn how to handle errors in this situation.

Before starting, please get the code for the demo application we will use in this article by cloning the repository linked here (main branch). After running the application, you should see the error shown in the image below.

In this demo application, the main page (displaying the form) can only be accessed by the logged in user, but some errors have occurred (in this case it is artificial, but it can also happen legally), Causes the session variable to be assigned to null.

Note: For simplicity, authentication will not be implemented in the demo application.

This of course leads to an error, and now, the application completely crashes because it doesn't know how to handle the error!

Now, we will learn how to deal with this error to prevent our application from crashing, thereby significantly improving the user experience of the application.

Create an error page

To prevent the application from crashing, in the app/ directory, create a error.tsx file. Creating this file automatically creates a React error boundary that wraps the main page. Then, in the error.tsx file, export the following function:

"use client";

export default function Error() {
  return (
    <div className="grid h-screen px-4 bg-white place-content-center">
      <div className="text-center">
        <h1 className="font-black text-gray-200 text-9xl">401</h1>
        <p className="text-2xl font-bold tracking-tight text-gray-900 sm:text-4xl">
          未授權(quán)！
        </p>
        <p className="mt-4 text-gray-500">
          您必須登錄才能訪問此頁面
        </p>
        <button
          type="button"
          className="inline-block px-5 py-3 mt-6 text-sm font-medium text-white bg-indigo-600 rounded hover:bg-indigo-700 focus:outline-none focus:ring"
        >
          重試
        </button>
      </div>
    </div>
  );
}

Note: The error component must be a client component! Be sure to mark them as client components.

Exported functions will act as fallback components. If an error is thrown within the boundary, the error is caught and the fallback component is rendered, which should look like below.

When an error occurs, two props are passed to the error fallback component—the error object itself and a function (usually called reset) that tries to recover from the error:

"use client";

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

export default function Error({ error, reset }: ErrorProps) {
  // ...
}

We can now access the error message through the error prop and display it on the screen as follows:

<p className="mt-4 text-gray-500">
  {error.message || "您必須登錄才能訪問此頁面"}
</p>

When this function is called, the reset function will attempt to rerender the original content surrounded by the error boundary. If successful, the fallback error component will be replaced by the re-rendered content.

We can implement reset function calls in our button using the onClick handler:

<button
  type="button"
  onClick={() => reset()}
  className="inline-block px-5 py-3 mt-6 text-sm font-medium text-white bg-indigo-600 rounded hover:bg-indigo-700 focus:outline-none focus:ring cursor-pointer"
>
  重試
</button>

In this way, we successfully handled our mistakes!

Abstract Error Message

In an actual user authentication application, there may be many routes that must be protected, and if an authentication error occurs, you need to use the same authentication error message in multiple instances.

To abstract error messages (and not written repeatedly), we can easily create a custom exception related to authentication.

To do this, create a directory called lib and create a file called exceptions.ts in that directory. In this file, we can create and export custom authentication error exceptions as follows:

export class AuthRequiredError extends Error {
  constructor(message = "需要身份驗證才能訪問此頁面") {
    super(message);
    this.name = "AuthRequiredError";
  }
}

Now, we can throw this new custom AuthRequiredError on the main page instead of the regular Error:

export default function Home() {
  if (!session) throw new AuthRequiredError();
  // ...
}

This error will give us the default message passed in the constructor, or a more specific error we may need to pass later.

More information about error handling

Finally, let's take a look at some extras for layout and server errors.

Error in layout

Errors can occur anywhere in the application (not just page.tsx files), and the file routing system used by Next.js affects how error.tsx boundaries work in nested routing and layouts.

Errors will bubble to the nearest parent error boundary, which can be seen in the image below.

The nature of this error bubbling means that the error.tsx boundary does not capture errors in the layout file in the same section, because the error boundary wraps the layout file.

If an error occurs in the root layout or template, use the global-error.tsx file as shown in the figure below.

global-error.tsx Boundaries wrap the entire application, so make sure to add your own unique and tags when using this file. This error boundary catches any errors that other nested error.tsx boundary are not caught, so it will not be activated often.

Server Error

If an error occurs in the server component or during data acquisition, Next.js forwards the corresponding Error object to the nearest error.tsx boundary.

Conclusion and Next Steps

Although many developers think it is cumbersome to implement error handling, it is an important part of the application and successfully implementing error handling will significantly improve the user experience of the application.

Next.js makes this very easy with the App Router and error.tsx file conventions.

You can consult Next.js documentation on error handling for more information about error handling, and you can also view the completion code for this article on GitHub.

FAQs on Mastering Error Handling in Next.js using App Router

(The FAQs part is omitted here because the FAQs part of the original text has a high degree of duplication with the article content, and some problems are weakly correlated with the error handling mechanism of App Router. If necessary, you can add it according to the original text.)

The above is the detailed content of Mastering Next.js Error Handling with the App Router. For more information, please follow other related articles on the PHP Chinese website!