Hosting Javascript Libraries in ASP.NET Applications

Virtually every ASP.NET UI project utilizes Javascript to some degree. Many applications reference JQuery and various Javascript libraries. For most implementations, it's fine to use CDNs as the source for the application's Javascript libraries. Occasionally there are requirements that every element of an application be self-hosted; in other words, the application must be completely self contained. In these scenarios, it's important to automate as much of the Javascript library management as possible.

Node.js, and the Node Package Manager (NPM) specifically, make this relatively straightforward. Most common Javascript libraries are hosted at npmjs.com. When coupled with gulp.js and Visual Studio's Task Runner, you can automate Javascript library management.

In this example, we'll host JQuery and Bootstrap 5 in an ASP.NET application. This example uses Visual Studio 2022, Node.js, and gulp.js.

Setup with Node.js

Start by making sure Visual Studio 2022 and Node.js are installed on your machine. Next, you'll want to install gulp.js globally using NPM from the command line.

npm install -g gulp-cli
npm install -g gulp

Create or open an ASP.NET project in Visual Studio (creating an ASP.NET project is outside the scope of this post). Open a command prompt in the project's directory and run the following commands to install the Javascript libraries we're going to need.

npm install jquery
npm install bootstrap

Note: As of NPM version 5.0.0, you no long have to explicitly include the --save option when using npm-install. Before NPM 5.0.0, you would have to run npm install --save. So if you're familiar with NPM, --save was intentionally left off the commands above.

Note: For an actual production application, you should specify the versions of the NPM packages and upgrade consistently with intentional care.

At this point, we have the latest version of these Javascript libraries downloaded to our local application. They should have been saved under the node_modules directory inside our project. Additionally, NPM should have created a package.json file inside the project directory that contains information about the Javascript libraries that were installed.

Configure gulp.js

Now lets add gulp.js to the project by running the following from a command line inside the project:

npm install gulp

Let's also add del, which will allow gulp.js tasks to delete files using Javascript.

npm install del

Note: Depending on how the application will be built and deployed, you may want to install gulp and del with the --save-dev option, so these libraries are only installed for the development environment.

Open the package.json file in Visual Studio and manually add a property of "type": "module" to it, as in, the gulpfile.js will be an ES module. This is required to run the Javascript (ECMAScript) in the gulpfile.js that we'll be creating in the next step. The package.json file should now look something like:

{
  "type": "module",
  "dependencies": {
    "bootstrap": "^5.3.3",
    "del": "^7.1.0",
    "gulp": "^5.0.0",
    "jquery": "^3.7.1"
  }
}

If you don't set the "type" to "module", you'll encounter errors like:

SyntaxError: Cannot use import statement outside a module

Now we are ready to configure gulp.js to copy the Javascript libraries to the project's wwwroot directory when we build our application; the Javascript libraries will then be available to our application when running in a web server.

Manually add a gulpfile.js file to your ASP.NET project. This file defines tasks for the gulp.js process. This filename must be gulpfile.js. Below is a sample.

import gulp from "gulp";
import { deleteSync } from "del";

function clean() {
    return new Promise(function (resolve, reject) {
        try {
            deleteSync(['wwwroot/lib/**', '!wwwroot/lib'], { force: true });
            resolve();
        }
        catch (e) {
            console.log(e);
            reject();
        }
    });
}

function copyNodeModules() {
    var files = {
        "jquery": 'jquery/dist/**/*.{js,map,min.js,min.js.map}',
        "@popperjs": '@popperjs/core/dist/umd/**/*.js,map,min.js,min.js.map}',
        "bootstrap": 'bootstrap/dist/**/*.{js,map,min.js,min.js.map,css,min.css}'
    }

    return new Promise(function (resolve, reject) {
        try {
            for (var destinationDir in files) {
                gulp.src('node_modules/' + files[destinationDir])
                    .pipe(gulp.dest('wwwroot/lib/' + destinationDir));
            }

            resolve();
        }
        catch (e) {
            console.log(e);
            reject();
        }
    });
}

function defaultTask() {
    return new Promise(function (resolve, reject) {
        try {
            var tasks = gulp.series(clean, copyNodeModules);
            tasks();
            resolve();
        }
        catch (e) {
            console.log(e);
            reject();
        }
    });
}

export { clean, copyNodeModules, defaultTask as default };

This gulpfile.js defines three basic tasks: clean, copyNodeModules, and defaultTask. The clean task will delete all Javascript libraries from wwwroot\lib. The copyNodeModules task will copy all of the Javascript libraries to wwwroot\lib. Finally, the defaultTask will clean wwwroot\lib, then copy the libraries to wwwroot\lib.

Task Runner Explorer in Visual Studio

Open the Task Runner Explorer in Visual Studio (Ctrl+Alt+Bkspce) and select the UI project that contains the gulpfile.js. You should see the tasks that were exported from the gulpfile.js module (clean, copyNodeModules, and default).

By right-clicking a task, you can run it manually or configure these tasks to be triggered by Visual Studio build actions via Bindings.

After running the default or copyNodeModules task, you should see the Javascript libraries in the wwwroot/lib folder inside of Visual Studio.

Inside your ASP.NET UI Application, you can now reference the Javascript libraries from your local project using HTML similar to:

<link rel="stylesheet" href="~/lib/bootstrap/css/bootstrap.min.css" />

And:

<script src="~/lib/jquery/jquery.min.js"></script>
<script src="~/lib/bootstrap/js/bootstrap.bundle.min.js"></script>

When deploying the application, make sure that the contents of the wwwroot/lib directory are included in the deployment.

This demo was created using the following:

• Visual Studio 2022
• Running a .NET 8 ASP.NET Core Web App
• Node.js v22.5.1
• npm v10.8.2
• gulp-cli v3.0.0
• gulp v5.0.0
  

Source code: https://github.com/jharrell-bits/JavascriptLibraryDemo