Merge pull request #21440 from backstage/debug-setup

Add docs for how to debug with VSCode

docs/local-dev/cli-build-system.md

@@ -590,22 +590,25 @@ For your productivity working with unit tests it's quite essential to have your
 
 A complete launch configuration for VS Code debugging may look like this:
 
-```json
+```jsonc
 {
   "type": "node",
-  "name": "vscode-jest-tests",
+  "name": "vscode-jest-tests.v2",
   "request": "launch",
+  "args": [
+    "repo",
+    "test",
+    "--runInBand",
+    "--watchAll=false",
+    "--testNamePattern",
+    "${jest.testNamePattern}",
+    "--runTestsByPath",
+    "${jest.testFile}"
+  ],
   "console": "integratedTerminal",
   "internalConsoleOptions": "neverOpen",
   "disableOptimisticBPs": true,
-  "program": "${workspaceFolder}/node_modules/.bin/jest",
-  "cwd": "${workspaceFolder}",
-  "args": [
-    "--config",
-    "node_modules/@backstage/cli/config/jest.js",
-    "--runInBand",
-    "--watchAll=false"
-  ]
+  "program": "${workspaceFolder}/node_modules/.bin/backstage-cli"
 }
 ```
 

docs/local-dev/debugging.md

@@ -47,3 +47,28 @@ The resulting log should now have more information available for debugging:
 [1] 2023-04-12T00:51:44.118Z search info Collating documents for tools succeeded type=plugin documentType=tools
 [1] 2023-04-12T00:51:44.119Z backstage debug task: search_index_tools will next occur around 2023-04-11T21:01:44.118-04:00 type=taskManager task=search_index_tools
 ```
+
+## Debugger
+
+### VSCode
+
+In your `launch.json`, add a new entry with the following,
+
+```jsonc
+{
+    "name": "Start Backend",
+    "request": "launch",
+    "args": [
+        "package",
+        "start"
+    ],
+    "cwd": "${workspaceFolder}/packages/backend",
+    "program": "${workspaceFolder}/node_modules/.bin/backstage-cli",
+    "skipFiles": [
+        "<node_internals>/**"
+    ],
+    "type": "node"
+},
+```
+
+You may notice that the normal logs mentioned above do not get logged, this is an issue with the logging library we're using, `winston`, and is not easily solved. See [this thread](https://github.com/winstonjs/winston/issues/1544) for more information.