Debugging with Next.js and VSCode

This article explains and introduces how to create and configure launch.json in VSCode to debug Next.js, enabling breakpoint setting, interactive execution, and REPL.

I’ve been building a SPA SaaS app with React for the past few months, and I found myself stepping into the abyss of SPA-specific page speed issues, API throttling and caching, webpack bundle.js splitting, split chunks, and optimization problems - I was almost in despair.

Then I remembered SSR (Server-Side Rendering), and thought “Let’s try Next.js!” Last week, while refactoring existing code to migrate to Next.js, the issue that inevitably comes up is debugging and breakpoints.

I’ve been debugging Node.js programs for a while, so I was launching debug with npx by writing launch.json like this:

{
  "type": "pwa-node",
  "request": "launch",
  "name": "Nextjs",
  "program": "/home/yuis/.nvm/versions/node/v17.9.0/bin/npx",
  "args": [
    "next",
    "dev",
  ],
  "console": "integratedTerminal",
},

Most Node.js programs work with the above if they’re simple, but with Next.js, breakpoints were very slow to start, and there were times when breakpoints worked and times when they didn’t, which was noticeably unstable.

So I did a quick Google search and found that the official documentation mentions debugging with VSCode.

Advanced Features: Debugging | Next.js

There are three configurations there, and the third one worked well:

{
  "name": "Next.js: debug full stack",
  "type": "node-terminal",
  "request": "launch",
  "command": "npm run dev",
  "console": "integratedTerminal",
  "serverReadyAction": {
    "pattern": "started server on .+, url: (https?://.+)",
    "uriFormat": "%s",
    "action": "debugWithChrome"
  }
}

I didn’t try the second one that attaches to Chrome for client-side. Client-side JavaScript debugging has React source code with source maps, so you can debug from Chrome’s developer tools. In my experience, doing this in VSCode makes things heavy.

The third configuration above doesn’t have issues with unstable breakpoints, and it starts up whether you reload the page, change the URL route, or insert code before an error, so there’s no stress.

Also, debugging the production environment should probably work the same way if you change npm run dev to npm run start or npx next start.

For production environment debugging, automating the build is convenient:

# ./.vscode/launch.json
"preLaunchTask": "build",

# ./.vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "npm",
      "args": [
        "run",
        "build"
      ],
      "group": "build",
    }
  ]
}

By the way, the VSCode version is 1.64.2. It’s from February 2022, so about 6 months old… Since auto-update is disabled, it gets old before I notice. The debugging instability might be because of that, or maybe not.

However, it’s also common for things to become unstable because of newer versions, so if it’s unstable, try fixing it with the above launch.json and this VSCode version.

Summary

This article explained how to debug Next.js applications in Visual Studio Code (VSCode). Here are the key points:

1. launch.json Configuration: We use the launch.json file to set up debugging. We provided a configuration for debugging Next.js applications. The configuration includes properties such as:

   • "name": Name of the debug configuration
   • "type": Type of debugging (using “node-terminal”)
   • "request": Type of debug request (specifying “launch”)
   • "command": Command to execute (starting Next.js app with “npm run dev”)
   • "console": Type of debug console (using “integratedTerminal”)

2. Debug Configuration Stability: From multiple debug configurations, we selected one where breakpoints work stably and can enter code before errors. The "serverReadyAction" configuration is particularly important, used to wait for the server to start before beginning debugging.

3. Debugging in Production Environment: We provided build task and debug task configurations for debugging in production. This prepares you for debugging in production as well.

4. VSCode Version: We mentioned that the VSCode version at the time of writing was 1.64.2. Since older versions of VSCode may have more stable debugging, we recommended trying older versions if the latest version is unstable.

Using these configurations and approaches, you can debug Next.js applications in VSCode stably and effectively.