Library Manager: Client-side content manager for web apps

If you’re developing a modern web app, chances are your app will reference client-side JavaScript and CSS files like jQuery or bootstrap. Maybe you copy these from a previous project, download them, or use Bower. However, with Bower announcing they won’t be offering support into the future, we thought it time to produce a lightweight, effective solution for web developers to easily manage common client-side library files.

So, we are previewing a new tool: Library Manager – Available in Visual Studio 2017 v15.7 Preview 4.0 in the Web Development and .NET Core workloads.

Library Manager (“LibMan” for short) is Visual Studio’s experimental client-side library acquisition tool. It provides a lightweight, simple mechanism that helps users find and fetch library files from an external source (such as CDNJS) and place them in your project.

What LibMan is not

LibMan is not a package management system. If you’re happily using npm/yarn/(or something else), we encourage you to continue doing so. LibMan was not developed as a replacement for these tools. For example, the SPA templates (i.e. Angular and React) we ship for ASP.NET Core depend on npm and WebPack, and we have no plans to change that.

Why use LibMan?

  • If your project does not require additional tools (like Node, npm, Gulp, Grunt, WebPack, etc) and you simply want to acquire a couple of files, then LibMan might be for you.
  • LibMan lets you specify exactly where the files should be placed inside your project. (No additional build tasks or manual file copying required!)
  • LibMan provides the benefit of a much smaller footprint in your web project as it only downloads the files you need.

To learn more about the benefits of LibMan, check out this clip of Mads Kristensen talking about the initial prototype in his talk at Microsoft Build 2017.

How to use Library Manager

From a Web Project, you can include Library Manager by choosing selecting “Manage Client-Side Libraries…” from the Project menu or from the project context menu in Solution Explorer.

Project Menu    Project context menu in Solution Explorer
Library Manager menu items on Project menu    Project context menu in Solution Explorer

If it doesn’t already exist, the Library Manager configuration file (libman.json) will be created with some default content and added to the root of your project. It opens in the JSON editor.

To specify the library files required for your project, simply add them to the libman.json file. Contextual IntelliSense is available to help you fill out the fields.

Saving the file will trigger the Library Manager restore operation, which will download the specified files and libraries and add them to the current project in the prescribed destination folder. You can see the results of the restore operation in the Output window.

Sample web project with sample libman.json file

Library Manager Configuration

Provider
There are two provider options that have been built for version 1.0 of Library Manager: cndjs and filesystem.

  • The cdnjs provider will attempt to fetch specified library files from the CDNJS public distribution network.
  • The filesystem provider will attempt to fetch library files from a local or network drive and will copy them to the destination folder.

The library files will come from the “defaultProvider” specified at the top level unless otherwise overridden by a “provider” property in the individual library definition.

Library
The “library” is the unique name of the library as defined by the relevant provider.

  • For the cdnjs provider, library names have the format: [LibraryName]@[Version] (Eg. “jquery@3.3.1”)
  • For the filesystem provider, the library is the path to the folder containing the library files.
    (eg. “//NetworkShare/MyLib”, “C:/LocalLibs/MyLib”)

Note: When using the Visual Studio editor, be sure to specify the provider element first if you want contextual IntelliSense to list the available libraries.

Contextual IntelliSense showing all available versions of jquery, sorted by most recent

Files
By default, all files from the specified library will be included in your project. If you only want to include specific files from a library, you can specify the file names in a comma separated list in the “files” property.
     eg. “files”: [“jquery.min.js”, “jquery.min.map”]
Contextual IntelliSense provides a list of available files to make it easier to discover and select the files you’re after.

Contextual IntelliSense showing list of all files in the jQuery library, excluding those already used

Destination
The “destination” of a library is the folder within your project where the library files will be restored.

There are two ways to specify the destination for a library’s files. If a “defaultDestination” property is defined at the top level, then the library files will be copied there (within the directory structure that they exist at the provider location). If a “destination” is defined at the library level, it will override the defaultDestination. Both destination and defaultDestination are relative to the location of the libman.json file.

Clean and Restore operations

Restore on build
You can enable Library Manager to restore all library files during build. To do so, right-click the libman.json file and choose “Enable Restore on Build”. This will add the LibraryManager NuGet package (Microsoft.Web.LibraryManager.Build) to the project, which will trigger a restore as part of project build.

Context menu of libman.json, showing Restore, Clean and Enable Restore on Build...

Restore on demand
Library Manager will restore client-side libraries whenever the libman.json file is saved. You can also force the restore operation by choosing “Restore Client-Side Libraries” from the context menu of the libman.json file in Solution Explorer.

Clean library files
You can use the “Clean” item on the libman.json context menu to delete all library files defined in the libman.json (if they exist in the destinations specified).
Note: If restoring files through Visual Studio, Library Manager will automatically delete any files defined during the previous restore operation that are no longer being referenced in the libman.json file.

Feedback/Contributions

Microsoft’s Library Manager is open-source and available on GitHub at: https://github.com/aspnet/LibraryManager
We welcome contributions and suggestions. For details, see the Contribution Guide. If you have any feedback or bug reports, please feel free to open new issues on the Issues repo.