Updating Your JavaScript Libraries in ASP.NET Core 2.2

The ASP.NET Core 2.2 project templates include four JavaScript / CSS libraries by default including Bootstrap, jQuery, jQuery Validation and jQuery Unobtrusive Validation. These will quickly become out of date and at some point you will need to update them, at a minimum to get any security patches. We use to update these through NuGet, but those days are now behind us.

Hosted Files — The Easiest Option

By far the easiest option is to use their hosted versions. If you look at the _Layout.cshtml and _ValidationScriptsPartial.cshtml you will find references to the hosted versions of the included libraries by default within the environment tags. The environment tags listed as include=”Development” are used while you are developing and the exclude=”Development” versions are used when you deploy your website. More information about environment tags can be found here.

If you always want to use hosted files you can simplify this code from this:

<environment include="Development">
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
</environment>
<environment exclude="Development">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.1.3/css/bootstrap.min.css"
          asp-fallback-href="~/lib/bootstrap/dist/css/bootstrap.min.css"
          asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-test-value="absolute"
          crossorigin="anonymous"
          integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>
</environment>

to this:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.1.3/css/bootstrap.min.css"
          crossorigin="anonymous"
          integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>

To update your library going forward is a two step process:

1. Change the version number.
2. Update the that ugly integrity value by copying your new href into the search box on srihash.org.

Enter your href in the SRI Hash Generator to get the new integrity value.

If srihash does not return anything, your href is probably bad.

There are a some downsides to this approach.

1. You have to look for new library versions manually.
2. You can develop easily without an internet connection.
3. If the hosted JavaScript files are down for some reason, your site is down. That is why those environment tags have those fallback values.

LibMan — The Easy Option

A fairly new option to keeping your JavaScript files up to date is LibMan. If you have ever used NuGet packages, you are going to feel right at home. Let’s walk through this by updating Bootstrap with Visual Studio 2017.

Client-Side Library menu option.

1. Right click on the project name and select Add > Client Side Library
2. Change the Provider value to unpkg.
3. Enter bootstrap@4.3.1 in the Library field. (or whatever the latest version is)
4. Select Choose specific files:
5. Select all the files in the dist folder.
6. Leave the Target Location as wwwroot/lib/bootstrap/
7. Select Install.
8. Update your HTML references (_Layout.cshtml and _ValidationScriptsPartial.cshtml). See the above for how to do this.

A libman.json file will be added to your project and the wwwroot/lib/bootstrap files will be updated.

Let’s go through each of these options.

Client side library options.

Provider

The default provider is cdnjs which is an extremely popular hosting service for thousands of JavaScript libraries. LibMan does not host any files, it only points at service providers. cdnjs does not include the source files for the projects. Because of this I chose unpkg instead which hosts an entire copy of each projects source files.

Library

Entering the library name will search the provider for a match. If you are using unpkg the name of the libraries match their npm names. More on NPM in the nest section.

Include all library files or Choose specific files

You don’t have to include all the files from the library. You can pick and choose.

I chose to pick only the files in the dist folder in this example because those are the files you will reference from your application in most scenarios.

There is one common scenario I have encountered that requires the source code for the project. You will need the source files to do something like theming the look of Bootstrap.

Target

The target location for your file by default will be the library name in the wwwroot\lib folder.

Keeping Things Updated

• At any time you can click on the libman.json file and select Restore Client Side Libraries.
• You can edit a library name directly in the libman.json file and get suggestions for new version. Just delete the version number after the @ symbol to see the list.

IntelliSense is provided for library search and versions.

• You can have your project try to download missing client side libraries on every build by right clicking on libman.json and selecting Enable Restore Client Side Libraries on Build.

Visual Studio for Mac and Visual Studio Code

At this time, LibMan is not included in Visual Studio for Mac and there is no extension for Visual Studio Code. There is however a command line interface that is cross platform.

NPM — The Almost As Easy Option

NPM stands for Node Package Manager and its by far the most popular way to update JavaScript libraries. It is the NuGet of the JavaScript world.

Let’s walk through the same scenario to update Bootstrap but with NPM instead.

The NPM configuration file.

1. Right click on the project name and select Add > New Item
2. Search for npm in the top right corner of the new window.
3. Select npm Configuration File and leave the name as package.json
4. In the devDependencies start a new line.
5. Add double quotes and start typing the bootstrap.
6. Pick your version number.
7. Save the file.
8. Copy the files from node_modules to the lib folder. See below.
9. Update your HTML references (_Layout.cshtml and _ValidationScriptsPartial.cshtml). See the above for how to do this.

IntelliSense is provided for library search and versions in NPM as well.

Visual Studio will automatically download the packages to a node_module folder. But you won’t be able to see it because it is not included in your project. Don’t add this folder to your project! It is going to include all the source code and you don’t want all those files. Instead click on the Show All Files button in your Solution Explorer window.

Show All Files option.

So at this point it is very similar to LibMan but there is one small problem. You have to get the files you want from the node_modules folder to the lib folder in your wwwroot folder. Don’t reference files from the node_modules folder directly in your HTML! You can simply copy them by hand each time you update your NPM file, or you can use LibMan again.

When you add a Client Side library through LibMan, one of your provider options is filesystem. Just pick that and navigate to your node_modules folder for Bootstrap to get it from there. You will need to do this once for each folder because LibMan does not copy files from sub-folder at this time.

Picking local files with LibMan.

So for example, for Bootstrap you will have to do it twice. Once for the CSS files in the node_modules/bootstrap/dist/css/ folder and once for the JavaScript files in the node_modules/bootstrap/dist/js/ folder.

Visual Studio for Mac and Visual Studio Code

Guess what? Command line again. There are lots of intro to NPM articles on the web, like this one here.

WebPack — The Hard Option

Don’t do it for an MVC project. Just please, don’t go down this road until you understand what WebPack is, what it is meant for, and what it is not meant for. It is beyond the scope of this beginners article.

Updating JavaScript libraries is harder than it use to be. NuGet is no longer the preferred option, hosted files are faster in production and integrity values make sure the correct and complete JavaScript is delivered to your user.

But recent tooling with LibMan and NPM has made it a lot easier.