Updated Debugging Language Service in VS Code (markdown)

Author: orta

Debugging-Language-Service-in-VS-Code.md

@@ -1,9 +1,54 @@
-VS Code is designed around an extension model. TypeScript provides a server called TSServer that provides information for providing quick-info, completions, etc., and VS Code acts as a client which queries the server when this information is needed. For example, VS Code queries TSServer for quick-info when the user's mouse hovers over a variable. TSServer will respond with information such as the appropriate type, and the styling to apply to the text that describes the type.
+VS Code is designed around an extension model. TypeScript provides a server called TSServer that provides information which supports quick-info, completions, etc., then VS Code acts as a client which queries the server when this information is needed. 
+
+For example, VS Code queries TSServer for quick-info when the user's mouse hovers over a variable by sending a message to TSServer. TSServer will respond with information such as the appropriate type, and the styling to apply to the text that describes the type.
 
 Organizationally, the client-side code for communicating with the TypeScript server lives in [`extensions/typescript`](https://github.com/Microsoft/vscode/tree/master/extensions/typescript) in [the VS Code repository](https://github.com/Microsoft/vscode).<sup>1</sup>
 
 Meanwhile, the server-side code lives in `src/services` and `src/server` of [the TypeScript repository](https://github.com/Microsoft/TypeScript).
 
+## Using stable VS Code to Debug Stable TSServer
+
+There are two steps to this:
+
+- Launch VS Code with an extra environment variable, and different user profile.
+- Connect to this VS Code's TSServer.
+
+To launch VS Code with a different profile and a debug copy of TSServer:
+
+```sh
+# Sets the TSServer port to 5667, this can be any number
+# Sets the user-data directory to be ~/.vscode-debug/ instead of ~/.vscode/ 
+
+TSS_DEBUG=5667 code --user-data-dir ~/.vscode-debug/
+```
+
+This will open VS Code as a separate app from your current one, it may have some of your extensions but not your settings. As long as you consistently use the above command, then you can save settings for debugging between sessions.
+
+This will launch a debug TSServer which you can connect to from inside the TypeScript codebase. Open up the TypeScript codebase, and look at the debugging panel. At the top, look to see if there is a drop-down item for debugging by Attaching to VS Code TSServer then select that.
+
+If there isn't, copy the template of `.vscode/launch.template.json` to `.vscode/launch.json` and it should show up.
+
+Select the "Attach by ..." option in the dropdown for debugging and hit the play button, it will ask you to choose a node instance to connect to. In the above example we used the port 5667, look for that and select it.
+
+That should have you connected to the TSServer for the debugging app version of VS Code while you work in the production version.
+
+## Using Stable VS Code with Development TSServer
+
+
+VS Code chooses where to launch TSServer from via the setting: `typescript.tsdk`. Continuing from above, if you want to have your TSServer use a local copy of TypeScript then change this setting to:
+
+```json
+{
+    "typescript.tsdk": "/path/to/repo/TypeScript/built/local"
+}
+```
+
+This is probably enough for most contributors, but if you are doing heavy duty VS Code and TypeScript work, you may want to carry on.
+
+---
+
+## Development VS Code with Development TSServer
+
 We will use a stable version of VS Code to debug a development version of VS Code running against a development version of TSServer.
 
 1. Download/install a stable version of vs code.