How to Debug React Server Components

React Server Components (RSCs) improve application performance by rendering UI on the server, but they also change how developers must debug their code. Since Server Components do not run in the browser, traditional client-side debugging tools like the Chrome Console or React Developer Tools cannot inspect them directly. This guide explains how to debug React Server Components using terminal logs, Node.js inspection tools, Visual Studio Code, and framework-specific error boundaries.

Use Terminal Console Logs

Because React Server Components execute on the build server or edge runtime, any console.log() statements you place inside them will output to your terminal window rather than the browser’s developer tools.

To use this method: 1. Insert console.log(variable) inside your Server Component. 2. Trigger the component rendering by reloading the page. 3. Look at the terminal or command prompt where your local development server (such as Next.js) is running to view the output.

Debug with VS Code

Debugging Server Components in Visual Studio Code allows you to set breakpoints, pause execution, and inspect variables in real time.

To set up VS Code debugging for a Next.js application:

  1. Create a .vscode/launch.json file in the root of your project.
  2. Add the following configuration to target the Node.js server process:
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: Debug Server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    }
  ]
}
  1. Open your Server Component file and click to the left of the line numbers to set a breakpoint.
  2. Go to the Run and Debug view in VS Code (Ctrl+Shift+D or Cmd+Shift+D) and run Next.js: Debug Server-side.
  3. Navigate to the page in your browser. The code execution will pause at your breakpoint inside VS Code.

Use Chrome DevTools for Node.js

You can inspect the Node.js process running your Server Components using the Google Chrome browser’s native developer tools.

  1. Start your development server with the Node inspect flag. For example, in a Next.js project, run:

    NODE_OPTIONS='--inspect' npm run dev

  2. Open Google Chrome and navigate to chrome://inspect.

  3. Under Remote Target, locate your Node.js application and click inspect.

  4. A dedicated Chrome DevTools window will open. You can now use the Sources tab to find your server-side files, set breakpoints, and step through the execution of your Server Components.

Inspect Network Payloads

React Server Components do not return standard HTML; instead, they stream a serialized JSON-like data structure to the client. Analyzing this payload helps you verify what data the server is sending.

  1. Open your browser’s Developer Tools (F12) and go to the Network tab.
  2. Reload the page or trigger a transition that loads a Server Component.
  3. Look for the document request or the fetch request representing the page change.
  4. Inspect the Response tab. You will see the RSC payload, which includes the component structure, props, and fallback states. If a Server Component is not rendering correctly, checking this payload will tell you if the server failed to send the correct data.

Implement Error Boundaries

When a React Server Component throws an error during rendering, React will attempt to handle it gracefully on the client.

To capture and debug these errors: * Create an error.js file: Frameworks like Next.js allow you to place an error.js file in the route segment. This file acts as a React Error Boundary that automatically catches errors thrown in nested Server Components. * Inspect the Error Object: The error object passed to this component contains the error message. Note that in production, sensitive error details are omitted for security, but in development, the full stack trace of the server-side error will be visible in your console and on the screen overlay.