Libman or “Library Manager” is a new tool built into Visual Studio 2017 (version 15.8+) for managing simple client side dependencies. For example, if you just want to create a simple ASP.NET Core MVC web application with Bootstrap 4, you can quickly and easily pull in just the CSS and JavaScript files you need, and you can put them where you want them. Unlike the old days when we pulled in client side packages using the NuGet Package Manager and the package maker decided where the files went and you just had to deal with it (or deal with the consequences of moving them) or today when using NPM where everything goes into the node_modules folder, with Libman you get to choose where the files go in your project. Not only can you choose where the files go, but you can choose exactly the files you want and ignore the rest if you don’t need them in your project. Obviously there are still plenty of scenarios where NPM fits the bill perfectly, but for the projects where you just want to manage a few of small dependencies and you want to keep it “lean and mean”, Libman may just be the right choice.
Managing Libraries Using the GUI
You can add/manage files with the Library Manager in a couple of different ways.
The first way is through the dialog which can be invoked by right clicking on a folder in the solution and selecting “Add..” and then “Client Side Library…” from the context menu. As an example, lets say we want to update all of our libraries in the lib folder @ -/wwwroot/lib to be managed by Libman. (You’ll want to clean out the folder first if you are going to use Libman to manage all of your libraries.)
- Right click on the lib folder in -/wwwroot and select “Add..” and then “Client Side Library…”
- A dialog will open allowing you to select the library you would like to pull in.
- Choose a provider (More on this in a bit, we’ll leave it on cdnjs for now)
- Start typing the name of the library (jQuery in this case), you’ll get intellisense to help you find the packages available.
- Be sure to use tab to complete the library selection. This will fill in the version and populate the files list.
- You can also type jquery@ and you’ll get an auto complete list of all the available versions.
- I usually select “Choose specific files” and select the files I want in my project specifically.
- “Target Location” will be populated automatically from the location you right clicked on in your project and the name of the library you chose, but you can customize it if you like.
- And finally, just click install to add the file(s) to you project.
The first time you do this a libman.json file will be created in the root of your project. This acts a lot like the old package.config for NuGet packages in .NET Framework applications in that it keeps track of the relevant settings for Libman and lists all of the libraries being managed by Libman.
In order to replace all of the original libraries you’ll need to do this for each library and update the references to the individual items in the ~/Views/Shared/_Layout.cshtml and the ~/Views/Shared/_ValidationScriptsPartial.cshtml files. (The original libraries and version are jquery@3.3.1, jquery-validate@1.17.0, jquery-validation-unobtrusive@3.2.9, and twitter-bootstrap@3.3.7 .)
Managing Libraries Manually
The second way you can manage libraries is by right clicking the project and selecting “Manage Client-Side Libraries …”. This will open up the libman.json file at the root of your project to be edited. (If libman.json does not exist, one will be created for you.) Here’s an example of a new empty file:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": []
}
To add your first library to this file manually expand the brackets [] after libraries (libraries is an array) and start a new object with braces {}. Inside the braces add four new elements:
- “provider” – the value for this should be one of the following:
- “cdnjs” – use cdnjs.com as your provider.
- “unpkg” – use unpkg.com as your provider.
- “filesystem” – use your local file system.
- “location” – The path from the root of your project to put the library files into.
- “library” – The name of the library
- “files” – A Json array of file names.
Here’s what it might look like with cdnjs as the provider, the same location we used above (-/wwwroot/lib) for jquery 3.3.1.
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": [
{
"provider": "cdnjs",
"destination": "wwwroot/lib/jquery",
"library": "jquery@3.3.1",
"files": [
"jquery.js",
"jquery.min.js",
"jquery.min.map"
]
}
]
}
Microsoft has provided a nice editor experience for this file inside Visual Studio. You get autocomplete for just about everything including the library names and file names. If you set the insertion point inside of a library object a light bulb will show up in the margin you can click on or you can use ctrl-. to activate a menu of options to update or uninstall that library. Also notice line 3 “defaultProvider : “cdnjs”? This means that if you omit the provider in a given library then “cdnjs” will be the provider by default. You can also add a line “defaultLocation” : “my/default/path” which will allow you to omit the location in each of the library objects.
Summary
When I read the initial blog post about this new feature there was no GUI at all, just the Json file. At first I wasn’t a fan, but after trying it out and seeing the autocomplete work it began to grow on me. Now I still use the Json editor even with the GUI being available. It’s a simple, but useful tool that does exactly what is needed and nothing more (and I can finally control where my client side dependencies get installed).