Merge pull request #6258 from Mikejo5000/mikejo-br16

Node.js updates for npm and js library integration

Author: megvanhuygen

docs/javascript/develop-javascript-code-without-solutions-projects.md

@@ -21,7 +21,7 @@ Starting in Visual Studio 2017, you can [develop code without projects or soluti
 To get started, select **File** > **Open** > **Folder** from the toolbar. Solution Explorer displays all the files in the folder, and you can open any of the files to begin editing. In the background, Visual Studio indexes the files to enable npm, build, and debug features.
 
 > [!IMPORTANT]
-> Many of the features described in this article, including npm integration, require Visual Studio 2017 version 15.8 or later versions.
+> Many of the features described in this article, including npm integration, require Visual Studio 2017 version 15.8 or later versions. The Visual Studio **Node.js development** workload must be installed.
 
 ## npm integration
 

docs/javascript/javascript-in-vs-2019.md

@@ -1,6 +1,6 @@
 ---
 title: JavaScript and TypeScript in Visual Studio 2019
-ms.date: "03/27/2019"
+ms.date: "03/16/2020"
 ms.technology: vs-javascript
 ms.topic: conceptual
 dev_langs:
@@ -31,11 +31,39 @@ The option to restore to the legacy JavaScript language service is no longer ava
 Visual Studio 2019 provides several options for integrating TypeScript compilation into your project:
 
 * [The TypeScript NuGet package](https://www.nuget.org/packages/Microsoft.TypeScript.MSBuild). When the NuGet package for TypeScript 3.2 or higher is installed into your project, the corresponding version of the TypeScript language service gets loaded in the editor.
-* The TypeScript SDK, available by default in the Visual Studio installer, as well as a standalone SDK download from the [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.typescript-331-vs2017).
 * [The TypeScript npm package](https://www.npmjs.com/package/typescript). When the npm package for TypeScript 2.1 or higher is installed into your project, the corresponding version of the TypeScript language service gets loaded in the editor.
+* The TypeScript SDK, available by default in the Visual Studio installer, as well as a standalone SDK download from the [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.typescript-331-vs2017).
 
 For projects developed in Visual Studio 2019, we encourage you to use the TypeScript NuGet and npm packages for greater portability across different platforms and environments.
 
+One common usage for the NuGet package is to compile TypeScript using the .NET Core CLI. Unless you manually edit your project file to import build targets from a TypeScript SDK installation, the NuGet package is the only way to enable TypeScript compilation using .NET Core CLI commands such as `dotnet build` and `dotnet publish`.
+
+## Remove default imports (ASP.NET Core projects)
+
+In older projects that use the [non-SDK-style format](https://docs.microsoft.com/nuget/resources/check-project-format), you may need to remove some project file elements.
+
+If you are using the NuGet package for MSBuild support for a project, the project file must not import `Microsoft.TypeScript.Default.props` or `Microsoft.TypeScript.targets`. The files get imported by the NuGet package, so including them separately may cause unintended behavior.
+
+1. Right-click the project and choose **Unload Project**.
+
+1. Right-click the project and choose **Edit \<*project file name*\>**.
+
+   The project file opens.
+
+1. Remove references to `Microsoft.TypeScript.Default.props` and `Microsoft.TypeScript.targets`.
+
+   The imports to remove look similar to the following:
+
+   ```xml
+   <Import
+      Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props"
+      Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props')" />
+
+   <Import
+      Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
+      Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />
+   ```
+
 ## Projects
 
 UWP JavaScript apps are no longer supported in Visual Studio 2019. You cannot create or open JavaScript UWP projects (files with extension *.jsproj*). You can learn more using our documentation on [creating Progressive Web Apps (PWAs)](/microsoft-edge/progressive-web-apps/get-started) that run well on Windows.

docs/javascript/media/aspnet-core-ts-jquery-example.png

@@ -2,7 +2,7 @@
 title: "Manage npm packages"
 description: Visual Studio helps you to manage packages using the Node.js package manager (npm)
 ms.custom: "seodec18"
-ms.date: "06/06/2018"
+ms.date: "03/12/2020"
 ms.topic: "conceptual"
 ms.devlang: javascript
 author: "mikejo5000"
@@ -16,25 +16,31 @@ ms.workload:
 
 # Manage npm packages in Visual Studio
 
-npm allows you to install and manage packages for use in your Node.js applications. If you're unfamiliar with
-npm and want to learn more, go to the [npm documentation](https://docs.npmjs.com/).
+npm allows you to install and manage packages for use in your Node.js applications. Visual Studio makes it easy to interact with npm and issue npm commands through the UI or directly. If you're unfamiliar with npm and want to learn more, go to the [npm documentation](https://docs.npmjs.com/).
 
-Visual Studio makes it easy to interact with npm and issue npm commands through the UI or directly. You can use the following methods:
+Visual Studio integration with npm is different depending on your project type.
+* [Node.js](#nodejs-projects)
+* [ASP.NET Core](#aspnet-core-projects)
+* [Open folder (Node.js)](../javascript/develop-javascript-code-without-solutions-projects.md)
+
+> [!Important]
+> npm expects the *node_modules* folder and *package.json* in the project root. If your app's folder structure is different, you should modify your folder structure if you want to manage npm packages using Visual Studio.
+
+> [!NOTE]
+> For existing Node.js projects, use the **From existing Node.js code** solution template to enable npm in your project.
+
+## Node.js projects
+
+For Node.js projects, use one the following methods:
 * [Install packages from Solution Explorer](#npmInstallWindow)
 * [Manage installed packages from Solution Explorer](#solutionExplorer)
 * [Use the `.npm` command in the Node.js Interactive Window](#interactive)
 
 These features work together and synchronize with the project system and the *package.json* file in the project.
 
-> [!Important]
-> NPM expects the *node_modules* folder and *package.json* in the project root. If your app's folder structure is different, you should update your folder structure if you want to manage npm packages using Visual Studio.
-
-> [!NOTE]
-> For existing NPM projects, use the **From existing Node.js code** solution template.
-
-## <a name="npmInstallWindow"></a> Install packages from Solution Explorer
+### <a name="npmInstallWindow"></a> Install packages from Solution Explorer (Node.js)
 
-The easiest way to install npm packages is through the npm package installation window. To access this window, right-click the **npm** node in the project and select **Install New npm Packages**.
+For Node.js projects, the easiest way to install npm packages is through the npm package installation window. To access this window, right-click the **npm** node in the project and select **Install New npm Packages**.
 
 ![Install new npm package from solution explorer](../javascript/media/solution-explorer-install-package.png)
 
@@ -47,18 +53,21 @@ In this window you can search for a package, specify options, and install.
 * **Selected version** - Select the version of the package you want to install.
 * **Other npm arguments** - Specify other standard npm arguments. For example, you can enter a version value such as `@~0.8` to install a specific version that is not available in the versions list.
 
-You can see the progress of the installation in the npm tab in the Output window. This may take some time.
+You can see the progress of the installation in the **npm** output in the **Output** window. This may take some time.
+
+![npm output](../javascript/media/npm-output.png)
 
 > [!TIP]
-> You can search for scoped packages by prepending the search query with the scope you're interested in, for example, type `@types/mocha` to look for TypeScript definition files for mocha. Also, when installing type definitions for TypeScript, you can specify the TypeScript version you're targetting by adding `@ts2.6` in the npm argument field.
+> You can search for scoped packages by prepending the search query with the scope you're interested in, for example, type `@types/mocha` to look for TypeScript definition files for mocha. Also, when installing type definitions for TypeScript, you can specify the TypeScript version you're targeting by adding `@ts2.6` in the npm argument field.
 
-## <a name="solutionExplorer"></a>Manage installed packages in Solution Explorer
+### <a name="solutionExplorer"></a>Manage installed packages in Solution Explorer (Node.js)
 
 npm packages are shown in Solution Explorer. The entries under the **npm** node mimic the dependencies in the *package.json* file.
 
 ![Search npm package](../javascript/media/solution-explorer-status.png)
 
 ### Package status
+
 * ![Installed package](../javascript/media/installed-npm.png) - Installed and listed in package.json
 * ![Extraneous package](../javascript/media/extraneous-npm.png) - Installed, but not explicitly
 listed in package.json
@@ -69,7 +78,7 @@ Right-click a package node or the **npm** node to take one of the following acti
 * **Update packages** to the latest version
 * **Uninstall a package** and remove from *package.json*
 
-## <a name="interactive"></a>Use the .npm command in the Node.js Interactive Window
+### <a name="interactive"></a>Use the .npm command in the Node.js Interactive Window (Node.js)
 
 You can also use the `.npm` command in the Node.js Interactive Window to execute
  npm commands. To open the window, right-click the project in Solution Explorer and choose **Open Node.js Interactive Window**.
@@ -86,3 +95,51 @@ In the window, you can use commands such as the following to install a package:
  > [!Tip]
  > If your project doesn't contain a package.json file, use `.npm init -y` to create a new package.json file
  > with default entries.
+
+ ## ASP.NET Core projects
+
+For projects such as ASP.NET Core projects, you can integrate npm support in your project and use npm to install packages.
+* [Add npm support to a project](#npmAdd)
+* [Install packages using package.json](#npmInstallPackage)
+
+>[!NOTE]
+> For ASP.NET Core projects, you can also use [Library Manager](https://docs.microsoft.com/aspnet/core/client-side/libman/?view=aspnetcore-3.1) or yarn instead of npm to install client-side JavaScript and CSS files.
+
+### <a name="npmAdd"></a> Add npm support to a project (ASP.NET Core)
+
+If your project does not already include a *package.json* file, you can add one enable npm support by adding a package.json file to the project.
+
+1. To add the file, right-click the project in Solution Explorer and choose **Add** > **New Item**. Choose the **npm Configuration File**, use the default name, and click **Add**.
+
+   ![Add package.json to your project](../javascript/media/npm-add-package-json.png)
+
+1. Include one or more npm packages in the `dependencies` or `devDependencies` section of *package.json*. For example, you might add the following to the file:
+
+   ```json
+   "devDependencies": {
+      "gulp": "4.0.2",
+      "@types/jquery": "3.3.33"
+   }
+   ```
+
+When you save the file, Visual Studio adds the package under the **Dependencies / npm** node in Solution Explorer. If you don't see the node, right-click **package.json** and choose **Restore Packages**.
+
+>[!NOTE]
+> In some scenarios, Solution Explorer may indicate that an npm package is out of sync with *package.json* due to a known issue described [here](https://github.com/aspnet/Tooling/issues/479). For example, the package may appear as not installed when it is installed. In most cases, you can update Solution Explorer by deleting *package.json*, restarting Visual Studio, and re-adding the *package.json* file as described earlier in this article.
+
+### <a name="npmInstallPackage"></a>Install packages using package.json (ASP.NET Core)
+
+For projects with npm included, you can configure npm packages using `package.json`. Right-click the npm node in Solution Explorer and choose **Open package.json**.
+
+![Search npm package](../javascript/media/npm-add-package.png)
+
+IntelliSense in *package.json* helps you select a particular version of an npm package.
+
+![Search npm package](../javascript/media/npm-add-package-intellisense.png)
+
+When you save the file, Visual Studio adds the package under the **Dependencies / npm** node in Solution Explorer. If you don't see the node, right-click **package.json** and choose **Restore Packages**.
+
+It may take several minutes to install a package. Check progress on package installation by switching to **npm** output in the **Output** window.
+
+![npm output](../javascript/media/npm-output.png)
+

docs/javascript/media/aspnet-core-ts-jquery-intellisense.png

@@ -1,7 +1,7 @@
 ---
 title: "Create an ASP.NET Core app with TypeScript"
 description: In this tutorial, you create an app using ASP.NET Core and TypeScript
-ms.date: 01/03/2020
+ms.date: 03/16/2020
 ms.topic: tutorial
 ms.devlang: javascript
 author: mikejo5000
@@ -34,6 +34,7 @@ In this tutorial, you learn how to:
 > * Add the NuGet package for TypeScript support
 > * Add some TypeScript code
 > * Run the app
+> * Add a third-party library using npm
 
 ## Prerequisites
 
@@ -52,21 +53,26 @@ In this tutorial, you learn how to:
 
 Visual Studio manages files for a single application in a *project*. The project includes source code, resources, and configuration files.
 
+>[!NOTE]
+> To start with an empty ASP.NET Core project and add a TypeScript frontend, see [ASP.NET Core with TypeScript](https://www.typescriptlang.org/docs/handbook/asp-net-core.html) instead.
+
 In this tutorial, you begin with a simple project containing code for an ASP.NET Core MVC app.
 
 1. Open Visual Studio.
 
 1. Create a new project.
 
     ::: moniker range=">=vs-2019"
-    Press **Esc** to close the start window. Type **Ctrl + Q** to open the search box, type **ASP.NET**, then choose **ASP.NET Core Web Application - C#**. In the dialog box that appears, choose **Create**.
+    If the start window is not open, choose **File** > **Start Window**. On the start window, choose **Create a new project**. In the language drop-down list, choose **C#**. In the search box, type **ASP.NET**, then choose **ASP.NET Core Web Application**. Choose **Next**.
+
+    Type a name for the project and choose **Create**.
     ::: moniker-end
     ::: moniker range="vs-2017"
     From the top menu bar, choose **File** > **New** > **Project**. In the left pane of the **New Project** dialog box, expand **Visual C#**, then choose **.NET Core**. In the middle pane, choose **ASP.NET Core Web Application - C#**, then choose **OK**.
     ::: moniker-end
     If you don't see the **ASP.NET Core Web Application** project template, you must add the **ASP.NET and web development** workload. For detailed instructions, see the [Prerequisites](#prerequisites).
 
-1. After you choose **Create**, select **Web Application (Model-View-Controller)** in the dialog box, and then choose **Create**.
+1. In the dialog box that appears, select **Web Application (Model-View-Controller)** in the dialog box, and then choose **Create** (or **OK**).
 
    ![Choose the MVC template](../javascript/media/aspnet-core-ts-mvc-template.png)
 
@@ -206,6 +212,76 @@ In this tutorial, you begin with a simple project containing code for an ASP.NET
 
    The application pauses at the breakpoint. Now, you can inspect variables and use debugger features.
 
+## Add TypeScript support for a third-party library
+
+1. Follow instructions in [npm package management](../javascript/npm-package-management.md##aspnet-core-projects) to add a package to your project.
+
+   >[!NOTE]
+   > For ASP.NET Core projects, you can also use [Library Manager](https://docs.microsoft.com/aspnet/core/client-side/libman/?view=aspnetcore-3.1) or yarn instead of npm to install client-side JavaScript and CSS files.
+
+1. In this example, add a TypeScript definition file for jQuery to your project. Include the following in your *package.json* file.
+
+   ```json
+   "devDependencies": {
+      "@types/jquery": "3.3.33"
+   }
+   ```
+
+   This adds TypeScript support for jQuery. The jQuery library itself is already included in the MVC project template (look under wwwroot/lib in Solution Explorer). If you are using a different template, you may need to include the jquery npm package as well.
+
+1. If the package in Solution Explorer is not installed, right-click the npm node and choose **Restore Packages**.
+
+   >[!NOTE]
+   > In some scenarios, Solution Explorer may indicate that an npm package is out of sync with *package.json* due to a known issue described [here](https://github.com/aspnet/Tooling/issues/479). For example, the package may appear as not installed when it is installed. In most cases, you can update Solution Explorer by deleting *package.json*, restarting Visual Studio, and re-adding the *package.json* file as described earlier in this article.
+
+1. In Solution Explorer, right-click the scripts folder and choose **Add** > **New Item**.
+
+1. Choose **TypeScript File**, type *library.ts*, and choose **Add**.
+
+1. In *library.ts*, add the following code.
+
+   ```ts
+   var jqtest = {
+      showMsg: function (): void {
+         let v: any = jQuery.fn.jquery.toString();
+         let content: any = $("#ts-example-2")[0].innerHTML;
+         alert(content.toString());
+         $("#ts-example-2")[0].innerHTML = content + " " + v + "!!";
+      }
+   };
+
+   jqtest.showMsg();
+   ```
+
+   For simplicity, this code displays a message using jQuery and an alert.
+
+   With TypeScript type definitions for jQuery added, you get IntelliSense support on jQuery objects when you type a "." following a jQuery object, as shown here.
+
+   ![jquery IntelliSense](../javascript/media/aspnet-core-ts-jquery-intellisense.png)
+
+1. In _Layout.cshtml, update the script references to include `library.js`.
+
+   ```html
+   <script src="~/js/app.js"></script>
+   <script src="~/js/library.js"></script>
+   ```
+
+1. In Index.cshtml, add the following HTML to the end of the file.
+
+   ```html
+   <div>
+      <p id="ts-example-2">jQuery version is:</p>
+   </div>
+   ```
+
+1. Press **F5** (**Debug** > **Start Debugging**) to run the application.
+
+    The app opens in the browser.
+
+    Click **OK** in the alert to see the page updated to **jQuery version is: 3.3.1!!**.
+
+    ![jquery example](../javascript/media/aspnet-core-ts-jquery-example.png)
+
 ## Next steps
 
 You may want to learn more details about using TypeScript with ASP.NET Core.

docs/javascript/media/npm-add-package-intellisense.png

@@ -401,10 +401,6 @@ For this scenario, use Chrome.
    For Microsoft Edge (Chromium), also shut down all instances of Chrome. Because both browsers share the chromium code base, this gives the best results.
    ::: moniker-end
 
-   ::: 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. Start your browser with debugging enabled.
 
     ::: moniker range=">=vs-2019"