ASP.NET Core 2.2 with LibMan, NPM and Webpack 4

Javascript tooling is a mess. Every time that I start a new application, I'm always asking myself how I need to setup my tooling. Thankfully, there is a sane way of setting up your tooling that won't make you want to pull your hair out once you set it up. We'll explore how to setup tooling for using NPM modules in your ASP.NET Core [2.2] applications with LibMan and Webpack 4.

Modern logo of tooling

The example will be simple, but sufficient, in order for you to add your complexity that is needed for your application.

Source code

For those that came for just the source code, you can find that right here.

Overview

We are building a tooling pipeline that will take NPM modules, and use webpack to bundle them. Using LibMan, we will move them into the correct directory so our ASP.NET Core application can serve them.

An overview of our process we are building

Installation

We will be making use of webpack, LibMan and the NPM Task Runner explorer to make all these pieces fit together. Before we begin, make sure you have these things installed:

1. Node.js (NPM comes packaged with node)
2. Visual Studio 2017 v15.8 or later (with the ASP.NET and web development workload) (How might I do this?)
3. .NET Core 2.1 SDK or later (you can find it here)
4. Install the NPM Task Runner explorer
5. In the ASP.NET Core project you want to set up tooling for, run this in your Package Manager Console (You can find this window by going into Tools > NuGet Package Manager > Package Manager Console)
   

   dotnet tool install -g Microsoft.Web.LibraryManager.Cli

Setup your application

First, add your package.json file to your application. Right click your project and select Add > New Item. Choose Web > Scripts and select the npm Configuration File and click Add.

Adding a package.json file

Feel free to copy paste the following code and replace the contents of your package.json file you just added. The important pieces in this package.json file are the scripts as well as the devDependencies. If you have an existing package.json, make the necessary modifications to your existing file.

{
  "version": "1.0.0",
  "name": "asp.net",
  "private": true,
  "scripts": {
    "clean": "node ./clean.js",
    "libman": "libman clean && libman restore",
    "webpack": "webpack ./wwwroot/js/site.js --output ./wwwroot/dist/js/site.min.js --mode=development",
    "build": "npm run clean && npm run webpack",
    "postinstall": "npm run libman"
  },
  "dependencies": {
    
  },
  "devDependencies": {
    "fs": "0.0.2",
    "webpack": "4.29.0",
    "webpack-cli": "3.2.1"
  }
}

Create a clean.js file in your root project directory and replace its contents with the code below. This code will delete the dist files that are used by your application (when bundling your js and css with webpack).

// Cleans the output [distribution] files
var fs = require("fs");
var filesToClean = ["./wwwroot/dist/js/site.min.js"];

for (var i = 0; i < filesToClean.length; i++) {
    if (fs.existsSync(filesToClean[i])) {
        fs.unlinkSync(filesToClean[i]);
    }
}

Create a dist folder and two sub-folders, one for js files and one for css files. The reason we are making a dist folder in wwwroot is so your files are available to the application to use as well as making cleaning dist files simpler.

Creating the dist folder

Create your libman.json file by running this in a command prompt. libman init. You don't need to modify anything when it prompts you for a DefaultProvider.

Running libman init in Powershell

Process

In your day-to-day coding, you'll have some NPM modules you want to use in your application. The first step is adding them to your package.json file. I'll add a module I have published as a sample.

Adding an npm module

Next, run npm install to install said dependency, OR - you can right-click the package.json file in the Solution Explorer and click Restore Packages.

In order to actually use the npm module however, we need to include it's source code in our application. This is done today by bundling our js / related assets with webpack. A npm module can't be loaded on the web by itself, and that is where webpack fills the gap. 

This is a very rudimentary example, but to show how this works, go into site.js and add a require call to our dependency we just installed.

// Please see documentation at https://docs.microsoft.com/aspnet/core/client-side/bundling-and-minification
// for details on configuring this project to bundle and minify static web assets.

// Write your Javascript code.
var minify = require("gulp-cshtml-minify");

// Use minify in some way..

Now, if we were to bundle our application with the webpack task (npm run webpack), we should get all the dependencies filled, but we don't because the npm module source code isn't in the wwwroot folder. While we could configure ASP.NET to look in the node_modules folder for our source, what we really want to be doing is moving the NPM module's source code into the wwwroot directory. For that, we need to manually edit the libman.json file. (Additional information can be found here for your future reference).

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "provider": "filesystem",
      "library": "node_modules/gulp-cshtml-minify/",
      "files": [ "index.js" ],
      "destination": "wwwroot/lib/gulp-cshtml-minify/"
    }
  ]
}

And then run the libman task. (To open up the Task Runner explorer, go into View > Other Windows > Task Runner explorer).

Running the libman task

Tip - how do we know we need to copy the index.js file from the NPM package? In each NPM package, a root file is defined in the package itself that acts as an entry point into the module. Most NPM modules use index.js, but to check would be to look at the source repo OR look for an index.js in the Solution Explorer.

Looking for that source file

Once libman is run, we see our NPM module source code in the lib folder.

NPM module source file!

All we simply need to do now is run the build task whenever we make changes to our main js file, and webpack will bundle everything properly into our dist js file.

Running the build task

We are all set now! But be sure to change references to load the dist js file instead of the default wwwroot/js/site.min.js if using a ASP.NET web application template in your views/pages!

Improvements

There is obvious room for improvement in this process, but it is a start. Here are some of my own ideas, I'd be interested to know how you feel this could be improved.

1. Instead of running libman after installing NPM modules, create a node script that can modify/add the appropriate entry (index.js) file of a NPM module that's included in the package.json file.
2. Update clean.js so that you can remove all files within a given folder, instead of an array of files, or both.
3. Ensure that libraries that are moved to the /lib folder are not included in the project build, opting to only include the dist/ files.
4. Add default build commands for css files, and optionally other webpack options.