Debug Your Storefront Next App Locally

By default, the app server displays console messages in the terminal but you can’t observe code execution. This limitation can make it hard to debug the code that renders pages on the server side (or on your local machine). For enhanced debugging, start your local development server with an alternate command that runs an inspector process in Node.js that a debugger attaches to.

For more information about the inspector process in Node.js, see the Node.js documentation.

Attach the debugger included in many popular browsers and text editors to Node’s inspector process. Here are instructions for Google Chrome and Visual Studio Code.

Google Chrome

Open a terminal.
Go to your project directory.
Start your local dev server using pnpm dev:debug.
To confirm that the debugger is listening, look for a “Debugger listening” message in the terminal output.
Open Chrome and enter the URL chrome://inspect.
Click Open dedicated DevTools for Node.
DevTools opens in a new window.
To confirm that the debugger is attached, look for a “Debugger attached” message in the terminal output.
Set breakpoints, add debugger statements, and so on.
Load a page from your local development server in Chrome.
Use the dedicated window for debugging.

Now you can trace the execution of your server-side code!

To learn more about debugging with breakpoints in DevTools, see Chrome DevTools from Google.

Visual Studio Code

Open your project files in Visual Studio Code.
From the menu bar, click Terminal > New Terminal.
Start your local dev server using pnpm dev:debug.
Open the Command Palette. Shortcut for Windows: Ctrl + Shift + P. Shortcut for Mac Command + Shift + P.
Type the following command: “Debug: Attach to Node Process.”
A list of the Node processes appears. Choose the first one in the list.
To confirm that the debugger is attached, look for a “Debugger Attached” message in the terminal output.
Set breakpoints, add debugger statements, and so on.
Load a page from your local development server in your web browser.
Use the integrated debugger in Visual Studio Code for debugging.

Now you can trace the execution of your server-side code in Visual Studio Code!

To avoid having to attach the Node process repeatedly, open the Command Palette and enter “Debug: Toggle Auto Attach.” Toggle the setting to Always and restart your local dev server in the Visual Studio Code terminal.

Tip