Merge pull request #5741 from Mikejo5000/mikejo-nodejs

Updates for sourcemap debugging

Author: GitHubber17

docs/javascript/debug-nodejs.md

@@ -39,15 +39,13 @@ You can debug JavaScript and TypeScript code using Visual Studio. You can set an
 ## Debug client-side script
 
 ::: moniker range=">=vs-2019"
-Visual Studio provides client-side debugging support for Chrome and Microsoft Edge (Chromium) only. In some scenarios, the debugger automatically hits breakpoints in JavaScript and TypeScript code and in embedded scripts on HTML files.
+Visual Studio provides client-side debugging support for Chrome and Microsoft Edge (Chromium) only. In some scenarios, the debugger automatically hits breakpoints in JavaScript and TypeScript code and in embedded scripts on HTML files. For debugging client-side script in ASP.NET apps, see the blog post [Debug JavaScript in Microsoft Edge](https://devblogs.microsoft.com/visualstudio/debug-javascript-in-microsoft-edge-from-visual-studio/) and this [post for Google Chrome](https://devblogs.microsoft.com/aspnet/client-side-debugging-of-asp-net-projects-in-google-chrome).
 ::: moniker-end
 ::: moniker range="vs-2017"
-Visual Studio provides client-side debugging support for Chrome and Internet Explorer only. In some scenarios, the debugger automatically hits breakpoints in JavaScript and TypeScript code and in embedded scripts on HTML files.
+Visual Studio provides client-side debugging support for Chrome and Internet Explorer only. In some scenarios, the debugger automatically hits breakpoints in JavaScript and TypeScript code and in embedded scripts on HTML files. For debugging client-side script in ASP.NET apps, see the blog post [Client-side debugging of ASP.NET projects in Google Chrome](https://devblogs.microsoft.com/aspnet/client-side-debugging-of-asp-net-projects-in-google-chrome/).
 ::: moniker-end
 
-If your source is minified or created by a transpiler like TypeScript or Babel, the use of [source maps](#generate_sourcemaps) is required for the best debugging experience. Without source maps, you can still attach the debugger to a running client-side script. However, you may only be able to set and hit breakpoints in the minified or transpiled file, not in the original source file. For example, in a Vue.js app, minified script gets passed as a string to an `eval` statement, and there is no way to step through this code effectively using the Visual Studio debugger, unless you use source maps. In these more complex debugging scenarios, you might instead use Chrome Developer Tools or F12 Tools for Microsoft Edge.
-
-To attach the debugger from Visual Studio and hit breakpoints in client-side code, the debugger typically needs help to identify the correct process. Here is one way to enable this using Chrome.
+If your source is minified or created by a transpiler like TypeScript or Babel, the use of [source maps](#generate_sourcemaps) is required for the best debugging experience. Without source maps, you can still attach the debugger to a running client-side script. However, you may only be able to set and hit breakpoints in the minified or transpiled file, not in the original source file. For example, in a Vue.js app, minified script gets passed as a string to an `eval` statement, and there is no way to step through this code effectively using the Visual Studio debugger, unless you use source maps. In complex debugging scenarios, you might instead use Chrome Developer Tools or F12 Tools for Microsoft Edge.
 
 ### Attach the debugger to client-side script
 
@@ -62,7 +60,11 @@ For this scenario, use Chrome.
 
 1. Close all windows for the target browser.
 
-   Other browser instances can prevent the debugger from attaching.
+   Other browser instances can prevent the browser from opening with debugging enabled. (Browser extensions may be running and preventing full debug mode, so you may need to open Task Manager to find unexpected instances of Chrome.)
+
+   ::: moniker range=">=vs-2019"
+   For Microsoft Edge (Chromium), also shut down all instances of Chrome. Because both browsers use the chromium code base, this gives the best results.
+   ::: moniker-end
 
 2. Open the **Run** command from the Windows **Start** button (right-click and choose **Run**), and enter the following command:
 
@@ -85,19 +87,23 @@ For this scenario, use Chrome.
 
     The app is not yet running, so you get an empty browser page.
 
-3. Switch to Visual Studio and set a breakpoint in your source code. (Set the breakpoint in a line of code that allows breakpoints, such as a return statement or a var declaration).
+3. Switch to Visual Studio and then set a breakpoint in your source code, which might be a JavaScript file, TypeScript file, or a JSX file. (Set the breakpoint in a line of code that allows breakpoints, such as a return statement or a var declaration.)
 
     ![Set a breakpoint](../javascript/media/tutorial-nodejs-react-set-breakpoint-client-code.png)
 
-    If you need to find particular code in a large, generated file, use **Ctrl**+**F** (**Edit** > **Find and Replace** > **Quick Find**).
+    To find the specific code in a transpiled file, use **Ctrl**+**F** (**Edit** > **Find and Replace** > **Quick Find**).
+
+    For client-side code, to hit a breakpoint in a TypeScript file or JSX file typically requires the use of [sourcemaps](#generate_sourcemaps). A sourcemap must be configured correctly to support debugging in Visual Studio.
 
-4. Select your target browser as the debug target in Visual Studio, then press **Ctrl**+**F5** (**Debug** > **Start Without Debugging**) to run the app in the browser.
+4. (Webpack only) Follow instructions described in [Generate sourcemaps](#generate_sourcemaps).
+
+5. Select your target browser as the debug target in Visual Studio, then press **Ctrl**+**F5** (**Debug** > **Start Without Debugging**) to run the app in the browser.
 
     The app opens in a new browser tab.
 
-5. Choose **Debug** > **Attach to Process**.
+6. Choose **Debug** > **Attach to Process**.
 
-6. In the **Attach to Process** dialog box, get a filtered list of browser instances that you can attach to.
+7. In the **Attach to Process** dialog box, get a filtered list of browser instances that you can attach to.
 
     ::: moniker range=">=vs-2019"
     In Visual Studio 2019, choose the correct target browser, **JavaScript (Chrome)** or **JavaScript (Microsoft Edge - Chromium)** in the **Attach to** field, type **chrome** or **edge** in the filter box to filter the search results. If you created a browser configuration with a friendly name, choose that instead.
@@ -106,7 +112,7 @@ For this scenario, use Chrome.
     In Visual Studio 2017, choose **Webkit code** in the **Attach to** field, type **chrome** in the filter box to filter the search results.
     ::: moniker-end
 
-7. Select the browser process with the correct host port (localhost in this example), and select **Attach**.
+8. Select the browser process with the correct host port (localhost in this example), and select **Attach**.
 
     The port (for example, 1337) may also appear in the **Title** field to help you select the correct browser instance.
 
@@ -124,15 +130,19 @@ For this scenario, use Chrome.
     > [!TIP]
     > If the debugger does not attach and you see the message "Failed to launch debug adapter" or "Unable to attach to the process. An operation is not legal in the current state.", use the Windows Task Manager to close all instances of the target browser before starting the browser in debugging mode. Browser extensions may be running and preventing full debug mode.
 
-8. Because the code with the breakpoint may have already executed, refresh your browser page. If necessary, take action to cause the code with the breakpoint to execute.
+9. Because the code with the breakpoint may have already executed, refresh your browser page. If necessary, take action to cause the code with the breakpoint to execute.
 
     While paused in the debugger, you can examine your app state by hovering over variables and using debugger windows. You can advance the debugger by stepping through code (**F5**, **F10**, and **F11**).
 
-    You may hit the breakpoint in either the transpiled JavaScript or its mapped location in your TypeScript file (using sourcemaps), depending on your environment and browser state. Either way, you can step through code and examine variables.
+    You may hit the breakpoint in either the transpiled *.js* file or the source file, depending on which steps you followed previously, along with your environment and browser state. Either way, you can step through code and examine variables.
+
+   * If you need to break into code in a TypeScript or JSX source file and are unable to do it, use **Attach to Process** as described in the previous steps to attach the debugger. Make sure you that your environment is set up correctly:
 
-   * If you need to break into code in a TypeScript file and are unable to do it, use **Attach to Process** as described in the previous steps to attach the debugger. In Solution Explorer, open **Script Documents** and check if your TypeScript file (*.ts*) is listed. If it is listed, open it and set a breakpoint, and refresh the page in your browser (set the breakpoint in a line of code that allows breakpoints, such as the `return` statement or a `var` declaration).
+      * You closed all browser instances, including Chrome extensions (using the Task Manager), so that you can run the browser in debug mode. Make sure you start the browser in debug mode.
 
-       Alternatively, if you need to break into code in a TypeScript file and are unable to do it, try using the `debugger;` statement in the TypeScript file. If this fails, you may need to set breakpoints in the Chrome Developer Tools (or F12 Tools for Microsoft Edge) instead. For sourcemap files generated by bundlers like Webpack, the browser tools typically work best.
+      * Make sure that your sourcemap file includes a reference to to your source file that doesn't include unsupported prefixes such as *webpack:///*, which prevents the Visual Studio debugger from locating *app.tsx*. For example, this reference might be corrected to *./app.tsx*. You can do this manually in the sourcemap file or through a custom build modification.
+
+       Alternatively, if you need to break into code in a source file (for example, *app.tsx) and are unable to do it, try using the `debugger;` statement in the source file, or set breakpoints in the Chrome Developer Tools (or F12 Tools for Microsoft Edge) instead.
 
    * If you need to break into code in a transpiled JavaScript file (for example, *app-bundle.js*) and are unable to do it, remove the sourcemap file, *filename.js.map*.
 
@@ -145,13 +155,36 @@ Visual Studio has the capability to use and generate source maps on JavaScript s
 
 * A TypeScript project in Visual Studio generates source maps for you by default.
 
-* In a JavaScript project, you need to generate source maps using a bundler like webpack and a compiler like the TypeScript compiler (or Babel), which you can add to your project. For the TypeScript compiler, you must also add a *tsconfig.json* file. For an example that shows how to do this using a basic webpack configuration, see [Create a Node.js app with React](../javascript/tutorial-nodejs-with-react-and-jsx.md). For sourcemap files generated by bundlers like Webpack, the browser tools (**F12**) typically work best for debugging.
+* In a JavaScript project, you need to generate source maps using a bundler like webpack and a compiler like the TypeScript compiler (or Babel), which you can add to your project. For the TypeScript compiler, you must also add a *tsconfig.json* file. For an example that shows how to do this using a basic webpack configuration, see [Create a Node.js app with React](../javascript/tutorial-nodejs-with-react-and-jsx.md).
 
 > [!NOTE]
-> If you are new to source maps, please read [Introduction to JavaScript Source Maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) before continuing.
+> If you are new to source maps, please read [Introduction to JavaScript Source Maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) before continuing. 
 
 To configure advanced settings for source maps, use either a *tsconfig.json* or the project settings in a TypeScript project, but not both.
 
+To enable debugging using Visual Studio, you need to make sure that the reference(s) to your source file in the generated sourcemap are correct. For example, if you are using webpack, references in the sourcemap file include the *webpack:///* prefix, which prevents Visual Studio from finding a TypeScript or JSX source file. Specifically, when you correct this for debugging purposes, the reference to the source file (such as *app.tsx*), must be changed from something like *webpack:///./app.tsx* to something like *./app.tsx*, which enables debugging (the path is relative to your source file). The following example shows how you can correct sourcemaps with webpack, which is one of the most common bundlers.
+
+(Webpack only) If you are setting the breakpoint in a TypeScript of JSX file (rather than a transpiled JavaScript file), you need to update your webpack configuration. For example, in *webpack-config.js*, you might need to replace the following code:
+
+```javascript
+  output: {
+    filename: "./app-bundle.js", // This is an example of the filename in your project
+  },
+```
+
+with this code:
+
+```javascript
+  output: {
+    filename: "./app-bundle.js", // Replace with the filename in your project
+    devtoolModuleFilenameTemplate: '[resource-path]'  // Removes the webpack:/// prefix
+  },
+```
+
+This is a development-only setting to enable debugging of client-side code in Visual Studio.
+
+For complicated scenarios, the browser tools (**F12**) may work best for debugging.
+
 ### Configure source maps using a tsconfig.json file
 
 If you add a *tsconfig.json* file to your project, Visual Studio treats the directory root as a TypeScript project. To add the file, right-click your project in Solution Explorer, and then choose **Add > New Item > Web > Scripts > TypeScript JSON Configuration File**. A *tsconfig.json* file like the following gets added to your project.
@@ -182,7 +215,7 @@ If you add a *tsconfig.json* file to your project, Visual Studio treats the dire
 
 For more details about the compiler options, check the page [Compiler Options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) on the TypeScript Handbook.
 
-### Configure source maps using project settings
+### Configure source maps using project settings (TypeScript project)
 
 You can also configure the source map settings using project properties by right-clicking the project and then choosing **Project > Properties > TypeScript Build > Debugging**.
 
@@ -208,4 +241,4 @@ Debugging dynamically generated files is not automatic. You cannot automatically
 
    For Internet Explorer, go to **Solution Explorer > Script Documents > Windows Internet Explorer > YourPageName**.
 
-For more information, see [Client-side debugging of ASP.NET projects in Google Chrome](https://devblogs.microsoft.com/aspnet/client-side-debugging-of-asp-net-projects-in-google-chrome/).
+For more information, see [Client-side debugging of ASP.NET projects in Google Chrome](https://devblogs.microsoft.com/aspnet/client-side-debugging-of-asp-net-projects-in-google-chrome/).