Comment utiliser les outils de débogage avec Next.js

Cette documentation explique comment déboguer votre code frontend et backend Next.js avec un support complet des source maps en utilisant le débogueur VS Code, Chrome DevTools ou Firefox DevTools.

Tout débogueur capable de se connecter à Node.js peut également être utilisé pour déboguer une application Next.js. Vous trouverez plus de détails dans le Guide de débogage de Node.js.

Débogage avec VS Code

Créez un fichier nommé .vscode/launch.json à la racine de votre projet avec le contenu suivant :

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js : débogage côté serveur",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js : débogage côté client",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js : débogage côté client (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js : débogage full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Remarque : Pour utiliser le débogage Firefox dans VS Code, vous devrez installer l'extension Firefox Debugger.

npm run dev peut être remplacé par yarn dev si vous utilisez Yarn ou pnpm dev si vous utilisez pnpm.

Dans la configuration "Next.js : débogage full stack", serverReadyAction.action spécifie quel navigateur ouvrir lorsque le serveur est prêt. debugWithEdge signifie lancer le navigateur Edge. Si vous utilisez Chrome, changez cette valeur en debugWithChrome.

Si vous modifiez le numéro de port sur lequel votre application démarre, remplacez le 3000 dans http://localhost:3000 par le port que vous utilisez.

Si vous exécutez Next.js depuis un répertoire autre que la racine (par exemple si vous utilisez Turborepo), vous devez ajouter cwd aux tâches de débogage côté serveur et full stack. Par exemple : "cwd": "${workspaceFolder}/apps/web".

Allez maintenant dans le panneau Debug (Ctrl+Shift+D sur Windows/Linux, ⇧+⌘+D sur macOS), sélectionnez une configuration de lancement, puis appuyez sur F5 ou sélectionnez Debug: Start Debugging dans la palette de commandes pour démarrer votre session de débogage.

Utilisation du débogueur dans Jetbrains WebStorm

Cliquez sur le menu déroulant listant les configurations d'exécution, puis cliquez sur Edit Configurations.... Créez une configuration de débogage JavaScript Debug avec http://localhost:3000 comme URL. Personnalisez selon vos préférences (par exemple, navigateur pour le débogage, enregistrer comme fichier projet), puis cliquez sur OK. Exécutez cette configuration de débogage, et le navigateur sélectionné devrait s'ouvrir automatiquement. À ce stade, vous devriez avoir 2 applications en mode débogage : l'application NextJS node et l'application client/navigateur.

Débogage avec les DevTools des navigateurs

Code côté client

Démarrez votre serveur de développement comme d'habitude en exécutant next dev, npm run dev ou yarn dev. Une fois le serveur démarré, ouvrez http://localhost:3000 (ou votre URL alternative) dans votre navigateur préféré.

Pour Chrome :

Ouvrez les outils de développement de Chrome (Ctrl+Shift+J sur Windows/Linux, ⌥+⌘+I sur macOS)
Allez dans l'onglet Sources

Pour Firefox :

Ouvrez les outils de développement de Firefox (Ctrl+Shift+I sur Windows/Linux, ⌥+⌘+I sur macOS)
Allez dans l'onglet Debugger

Dans les deux navigateurs, chaque fois que votre code côté client atteint une instruction debugger, l'exécution du code sera mise en pause et ce fichier apparaîtra dans la zone de débogage. Vous pouvez également rechercher des fichiers pour définir des points d'arrêt manuellement :

Dans Chrome : Appuyez sur Ctrl+P sur Windows/Linux ou ⌘+P sur macOS
Dans Firefox : Appuyez sur Ctrl+P sur Windows/Linux ou ⌘+P sur macOS, ou utilisez l'arborescence des fichiers dans le panneau de gauche

Notez que lors de la recherche, vos fichiers sources auront des chemins commençant par webpack://_N_E/./.

Code côté serveur

Pour déboguer le code côté serveur Next.js avec les DevTools des navigateurs, vous devez passer le flag --inspect au processus Node.js sous-jacent :

Terminal

NODE_OPTIONS='--inspect' next dev

Bon à savoir : Utilisez NODE_OPTIONS='--inspect=0.0.0.0' pour permettre un accès de débogage distant en dehors de localhost, par exemple lors de l'exécution de l'application dans un conteneur Docker.

Si vous utilisez npm run dev ou yarn dev, vous devez mettre à jour le script dev dans votre package.json :

package.json

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

Le lancement du serveur de développement Next.js avec le flag --inspect ressemblera à ceci :

Terminal

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Pour Chrome :

Ouvrez un nouvel onglet et visitez chrome://inspect
Cliquez sur Configure... pour vous assurer que les deux ports de débogage sont listés
Ajoutez localhost:9229 et localhost:9230 s'ils ne sont pas déjà présents
Cherchez votre application Next.js dans la section Remote Target
Cliquez sur inspect pour ouvrir une fenêtre séparée des DevTools
Allez dans l'onglet Sources

Pour Firefox :

Ouvrez un nouvel onglet et visitez about:debugging
Cliquez sur This Firefox dans la barre latérale gauche
Sous Remote Targets, trouvez votre application Next.js
Cliquez sur Inspect pour ouvrir le débogueur
Allez dans l'onglet Debugger

Le débogage du code côté serveur fonctionne de manière similaire au débogage côté client. Lors de la recherche de fichiers (Ctrl+P/⌘+P), vos fichiers sources auront des chemins commençant par webpack://{nom-de-l-application}/./ (où {nom-de-l-application} sera remplacé par le nom de votre application selon votre fichier package.json).

Inspection des erreurs serveur avec les DevTools des navigateurs

Lorsque vous rencontrez une erreur, l'inspection du code source peut aider à retracer la cause racine des erreurs.

Next.js affichera une icône Node.js sous l'indicateur de version Next.js dans l'overlay d'erreur. En cliquant sur cette icône, l'URL des DevTools est copiée dans votre presse-papiers. Vous pouvez ouvrir un nouvel onglet du navigateur avec cette URL pour inspecter le processus serveur Next.js.

Débogage sur Windows

Les utilisateurs Windows peuvent rencontrer un problème en utilisant NODE_OPTIONS='--inspect' car cette syntaxe n'est pas supportée sur les plateformes Windows. Pour contourner ce problème, installez le package cross-env comme dépendance de développement (-D avec npm et yarn) et remplacez le script dev par ce qui suit.

package.json

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

cross-env définira la variable d'environnement NODE_OPTIONS quel que soit le système d'exploitation (y compris Mac, Linux et Windows) et vous permettra de déboguer de manière cohérente entre les appareils et les systèmes d'exploitation.

Bon à savoir : Assurez-vous que Windows Defender est désactivé sur votre machine. Ce service externe vérifie chaque lecture de fichier, ce qui a été signalé comme augmentant considérablement le temps de Fast Refresh avec next dev. Il s'agit d'un problème connu, non lié à Next.js, mais qui affecte le développement avec Next.js.

Plus d'informations

Pour en savoir plus sur l'utilisation d'un débogueur JavaScript, consultez la documentation suivante :

Comment utiliser les outils de débogage avec Next.js

On this page