From 7a9ea65687ed164c67f8780daa366ec8558f9547 Mon Sep 17 00:00:00 2001 From: Bernd Schoolmann Date: Wed, 3 Jun 2026 20:00:16 +0900 Subject: [PATCH 1/3] Add notes about attaching debuggers --- docs/getting-started/clients/debugging.mdx | 53 +++++++++++++++++++ .../getting-started/clients/desktop/index.mdx | 13 ++--- .../clients/web-vault/index.mdx | 5 ++ 3 files changed, 61 insertions(+), 10 deletions(-) create mode 100644 docs/getting-started/clients/debugging.mdx diff --git a/docs/getting-started/clients/debugging.mdx b/docs/getting-started/clients/debugging.mdx new file mode 100644 index 000000000..e167a122f --- /dev/null +++ b/docs/getting-started/clients/debugging.mdx @@ -0,0 +1,53 @@ +--- +sidebar_position: 6 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import CodeBlock from "@theme/CodeBlock"; + +# Debugging with VS Code + +The clients repository ships VS Code launch configurations in its `.vscode` folder, so you can +attach the debugger to the Desktop app and the Web Vault without any extra setup. Open the +**Run and Debug** panel and select a configuration from the dropdown. + +## Desktop + +Electron apps have a renderer process, which runs in the Electron window, and the main process, +which runs in the background. + +Select **`Desktop: Attach Debugger (main + renderer)",`** from the Run and Debug dropdown. This attaches VSCode's +debugger to a running desktop client. You can then set breakpoints directly in the TypeScript source. + +:::tip + +The renderer process can also be inspected using the Chromium DevTools, which open automatically +when the Desktop app opens, or which you can open from the "View" menu. + +::: + +## Web Vault + +First, build and serve the [Web Vault](./web-vault/index.mdx). + +Next, launch Chrome with remote debugging enabled, using a dedicated profile so it doesn't interfere +with your normal browser session: + + + + {`open -a "Google Chrome" --args --remote-debugging-port=9223 --user-data-dir=remote-debug-profile`} + + + {`chrome.exe --remote-debugging-port=9223 --user-data-dir=remote-debug-profile`} + + + {`google-chrome --remote-debugging-port=9223 --user-data-dir=remote-debug-profile`} + + + +Then, in the Chrome instance you just launched, navigate to `https://localhost:8080`. + +Finally, in VS Code, select **`Web: Renderer (attach)`** from the Run and Debug dropdown to attach +the debugger. You can then set breakpoints directly in the TypeScript source. + diff --git a/docs/getting-started/clients/desktop/index.mdx b/docs/getting-started/clients/desktop/index.mdx index 593ed0652..a43a2b1dd 100644 --- a/docs/getting-started/clients/desktop/index.mdx +++ b/docs/getting-started/clients/desktop/index.mdx @@ -101,17 +101,10 @@ cd apps/desktop npm run electron ``` -## Debugging and testing +## Debugging -Electron apps have a renderer process, which runs in the Electron window, and the main process, -which runs in the background. - -The renderer process can be inspected using the Chromium debugger. It should open automatically when -the Desktop app opens, or you can open it from the “View” menu. - -The main process can be debugged by running the app from a -[Javascript Debug Terminal](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal) -in Visual Studio Code and then placing breakpoints in `build/main.js`. +See [Debugging with VS Code](../debugging.mdx#desktop) for how to attach the VS Code debugger to the +main and renderer processes. ## Biometric unlock (Native Messaging) diff --git a/docs/getting-started/clients/web-vault/index.mdx b/docs/getting-started/clients/web-vault/index.mdx index eee3d30f5..6c957fb20 100644 --- a/docs/getting-started/clients/web-vault/index.mdx +++ b/docs/getting-started/clients/web-vault/index.mdx @@ -139,3 +139,8 @@ following structure: [^1]: `urls` adhere to the [type definition in `EnvironmentService`](https://github.com/bitwarden/clients/blob/main/libs/common/src/platform/abstractions/environment.service.ts). + +## Debugging + +See [Debugging with VS Code](../debugging.mdx#web-vault) for how to attach the VS Code debugger to +the Web Vault running in Chrome. From aa1b5fb53a0568936a98f7bf8a47a4bef25c1254 Mon Sep 17 00:00:00 2001 From: Bernd Schoolmann Date: Wed, 3 Jun 2026 20:02:15 +0900 Subject: [PATCH 2/3] Cleanup --- docs/getting-started/clients/debugging.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/clients/debugging.mdx b/docs/getting-started/clients/debugging.mdx index e167a122f..870671145 100644 --- a/docs/getting-started/clients/debugging.mdx +++ b/docs/getting-started/clients/debugging.mdx @@ -9,16 +9,17 @@ import CodeBlock from "@theme/CodeBlock"; # Debugging with VS Code The clients repository ships VS Code launch configurations in its `.vscode` folder, so you can -attach the debugger to the Desktop app and the Web Vault without any extra setup. Open the -**Run and Debug** panel and select a configuration from the dropdown. +attach the debugger to the Desktop app and the Web Vault without any extra setup. Open the **Run and +Debug** panel and select a configuration from the dropdown. ## Desktop Electron apps have a renderer process, which runs in the Electron window, and the main process, which runs in the background. -Select **`Desktop: Attach Debugger (main + renderer)",`** from the Run and Debug dropdown. This attaches VSCode's -debugger to a running desktop client. You can then set breakpoints directly in the TypeScript source. +Select **`Desktop: Attach Debugger (main + renderer)",`** from the Run and Debug dropdown. This +attaches VSCode's debugger to a running desktop client. You can then set breakpoints directly in the +TypeScript source. :::tip @@ -50,4 +51,3 @@ Then, in the Chrome instance you just launched, navigate to `https://localhost:8 Finally, in VS Code, select **`Web: Renderer (attach)`** from the Run and Debug dropdown to attach the debugger. You can then set breakpoints directly in the TypeScript source. - From df6ae736409249da977524c3b28084de68be854a Mon Sep 17 00:00:00 2001 From: Bernd Schoolmann Date: Wed, 3 Jun 2026 20:05:22 +0900 Subject: [PATCH 3/3] Fix typo --- docs/getting-started/clients/debugging.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/clients/debugging.mdx b/docs/getting-started/clients/debugging.mdx index 870671145..eb3ecf256 100644 --- a/docs/getting-started/clients/debugging.mdx +++ b/docs/getting-started/clients/debugging.mdx @@ -17,7 +17,7 @@ Debug** panel and select a configuration from the dropdown. Electron apps have a renderer process, which runs in the Electron window, and the main process, which runs in the background. -Select **`Desktop: Attach Debugger (main + renderer)",`** from the Run and Debug dropdown. This +Select **`Desktop: Attach Debugger (main + renderer)`** from the Run and Debug dropdown. This attaches VSCode's debugger to a running desktop client. You can then set breakpoints directly in the TypeScript source.