How to Debug Multiple Services with Compound Configurations in VS Code

When your project has a frontend and a backend, a client and a server, or multiple microservices, you need to debug them together. VS Code compound configurations let you start all of them with a single press of F5. Each service still needs its own entry in launch.json first.

How compounds work

A compound configuration groups two or more existing configurations and launches them together. Each service still gets its own debug session, its own call stack, and its own breakpoints. The difference is that you start them all at once instead of one at a time.

Define each service as a separate configuration first. Here is a server that listens on port 4000. Give each configuration a unique, descriptive name because the compound will reference those names later.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Server",
  "program": "${workspaceFolder}/server/index.js",
  "args": ["--port", "4000"]
}

And here is a client on port 3000. Both configurations use the same debugger type and launch request. The only differences are the name, program path, and port argument.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Client",
  "program": "${workspaceFolder}/client/index.js",
  "args": ["--port", "3000"]
}

Now group them into a compound. The compounds array sits at the top level of your launch settings, next to configurations.

json

"compounds": [
  {
    "name": "Debug Full Stack",
    "configurations": ["Launch Server", "Launch Client"]
  }
]

Select "Debug Full Stack" from the Run and Debug dropdown. Press F5. Both the server and client start. Two debug sessions appear in the CALL STACK section.

Debug client and server (frontend + backend)

A common full-stack setup launches a backend API server and a browser for the frontend. The backend uses the Node.js debugger type and sets its port through an environment variable. The frontend uses the Chrome debugger type with the URL of your development server and the webRoot pointing to the source folder.

json

{
  "type": "node",
  "request": "launch",
  "name": "Backend API",
  "program": "${workspaceFolder}/api/server.js",
  "env": { "PORT": "4000" }
}

The frontend configuration opens a browser pointing at your dev server. The webRoot field is critical because it tells the debugger where to find your source files on disk.

json

{
  "type": "chrome",
  "request": "launch",
  "name": "Frontend Browser",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}/frontend"
}

Group them in a compound so one press of F5 starts both. The compound configuration references the backend and frontend by their names:

json

"compounds": [
  {
    "name": "Full Stack",
    "configurations": ["Backend API", "Frontend Browser"]
  }
]

Start "Full Stack" and you get a debugger for your API code and a debugger for your browser JavaScript. Set breakpoints in both. They work independently.

Wait for a dependency

If your frontend needs the backend to be running before it loads, add a preLaunchTask to the frontend configuration. The pre-launch task runs a script that waits for the backend port to be available before the frontend starts.

json

{
  "type": "chrome",
  "request": "launch",
  "name": "Frontend Browser",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}/frontend",
  "preLaunchTask": "Wait for Backend"
}

Define the "Wait for Backend" task in your tasks file. A simple shell task can use curl or a similar command to poll the backend port until it responds.

Stop all sessions together

By default, stopping one session in a compound does not stop the others. To stop everything at once when any session ends, set stopAll to true.

json

{
  "compounds": [
    {
      "name": "Full Stack",
      "configurations": ["Backend API", "Frontend Browser"],
      "stopAll": true
    }
  ]
}

You can also set stopAll on individual configurations. When that specific configuration stops, all sessions stop.

Multi-target debugging UI

When multiple sessions are running, the VS Code UI changes to show them all.

The CALL STACK section shows each session as a top-level node. Expand a session to see its call stack frames. Click a frame to switch to that session and inspect its variables.

The debug toolbar shows the name of the active session. A dropdown next to the name lets you switch to another session. Debug actions like Step Over, Continue, and Stop apply to the active session only.

Each session has its own Debug Console. Switch between them using the session selector in the console toolbar.

Breakpoints are shared across sessions. A breakpoint set in your source code triggers regardless of which session reaches it.

Troubleshooting

One service starts before the other is ready

Add a preLaunchTask to the dependent service. The task should poll or wait until the dependency is available. For HTTP services, a script that curls the health endpoint works well. For databases, wait for the port to be open.

Sessions conflict on the same port

Make sure each service uses a different port. Set the port in each configuration's args or env field. If the port is hardcoded in your code, use environment variables to override it.

A session stops and the other keeps running

This is the default behavior. Add stopAll: true to the compound or to the individual configuration to stop all sessions when one stops.

The debug toolbar shows the wrong session

The active session is the one highlighted in the CALL STACK section. Click a different session or use the dropdown in the debug toolbar to switch. The active session name is always visible in the toolbar.