Bundling in .NET Core MVC Applications with BundlerMinifier.Core

Today’s header image was created by Annie Spratt, the original source for the image is available here

I mentioned, last week, that there are a lot of options when it comes to bundling. Today I’m going to discuss another of those options: BundlerMinifier.Core

If you’re confused as to what bundling is or why we should do it, then check out last week’s article on bundling with webpack.

What Is It?

BundlerMinifier.Core is a .NET Core compatible build of BundlerMinifier by Mads Kristensen.

Wait, I know that name.

You might recognise his name, because he’s one of the Senior Program Managers at Microsoft. He also created (amongst others) the WebEssentials, NpmTaskRunner, and BrowserSync extensions for Visual Studio.

How Do I Add BundlerMinifier.Core To My App?

There are two ways to add BundlerMinifier.Core:

• The Easy Way
• The Hard Way

If you haven’t created your MVC app yet, then we can take the easy way. If you’ve already started work on your MVC app, then we’ll have to go the hard way.

Don’t worry, it’s not hard at all. I’ll show you how.

The Hard Way

We’re going to start with an MVC application that you’ve already been working on. Perhaps while testing you’ve noticed that your pages load slowly because they make lots of GET requests for resources. Well, lets increase the speed of your page by setting up bundling.

Adding BundlerMinifier.Core

Open your project in Visual Studio Code, and open on your project.json. Once you’ve got the project.json open, add the following line to the dependencies section:

Version 2.2.306 was the latest stable version as this post was published. You can check the NuGet packages page for the latest version

Before we can continue we’ll need to restore packages. If Visual Studio Code tells you to restore your packages, then let it do that for you. Otherwise, head over to the terminal and run our favourite restore command:

After CDing into the correct directory, of course.

Adding a Bundler Config

Add a file to the root of your project called bundleconfig.json and paste the following code in:

There’s a lot going on, so let’s quickly dissect it’s contents.

Each object in the outer array within the config file tells BundlerMiniifier.Core to do a separate task. The first being to bundle our CSS:

Here we’re creating a single CSS bundle which will be outputted as site.min.css in the wwwroot/css directory. We’re also only including a single css file (‘site.css’ in the wwwroot/css directory – which is where static files are served from), but we can add as many as we want to be included in this bundle.

In your application, you’ll need to add an entry for each of the bundles that you need – perhaps a single entry per page, or an entry for the common CSS.

Then we’re creating a JS minification bundle, which will be outputted as site.min.js in the wwwroot/js directory. As with the CSS bundle, we’re only adding a single js file, but we can add as many as we need for this bundle.

The two major differences between CSS and JS bundling (which I’ve highlighted) provide minification and source maps for our bundled JS files.

Again, as with the CSS bundles, we can add as many entries as we need

A Quick Note About Minifiation

From Wikipedia:

Minification (also minimisation or minimization), in computer programming languages and especially JavaScript, is the process of removing all unnecessary characters from source code without changing its functionality. These unnecessary characters usually include white space characters, new line characters, comments, and sometimes block delimiters, which are used to add readability to the code but are not required for it to execute.

What we’re going to do is tell BundlerMinifier.Core to remove any characters from the bundled files which match the above criteria. This will make the bundled files smaller, which means that the browser will spend less time downloading them, which in turn will make our pages load faster.

Once they’re cached by the browser, obviously.

Bundling on Compilation

Once your packages have been restored and you’ve added your config, we can tell Roslyn to run the bundler before compiling your project by adding the following to your project.json:

This will tell Roslyn to bundle your JS and CSS (via the dotnet bundle command) before starting any compilation tasks.

The Easy Way

Let’s say that you haven’t created your MVC project yet, but you want to add bundling to it via BundlerMinifier.Core when you do create it. Let’s do that for with a new project, with our old pal the Yeoman Generator.

Always with the Yeoman Generator, Jamie

Choose Web Application as the project type and give the project a name (I chose Mvc-with-bundlerminifier-core).

I chose that name because I hate myself, apparently

Whether you choose Bootstrap or SemanticUI is a choice that you will have to make, based on what your project needs.

Then cd into the directory and restore packages.

Open the directory with VS Code, and you’ll notice that BundlerMinifier.Core has been added to your project.json:

Yeoman has even added the pre-compile entry for us:

It’s also added the bundeconfig.json for us:

So the easy way is just: create a new app? Cool

Running BundlerMinifier.Core

Regardless of whether we take the Hard Way or the Easy Way, you have two ways to tell Roslyn to bundle your CSS and JS:

• Running from the terminal
• Building or Running your application

Bundling from the terminal

To run from the terminal, just run the following command:

This will open the bundlerconfig.json file in the root of your project and run each of the bundles found in it. The default configuration will provide something similar to this output:

Building or Running The Application

Building and running from the terminal will provide the similar output to the following (after issuing the dotnet run command):

In both instances, we can see that BundlerMinifier.Core actually bundled and minified our content files:

Other bundle Commands

There are two other options for the bundle command which useful to know:

• clean
• watch

clean

The clean command will tell Roslyn to delete any of the bundled files that it has previously generated. In our configuration, this means the site.min.js and site.min.css files.

Here is how you run the clean command:

Which will produce output similar to this:

I’ve highlighted two lines here, because what’s outputted isn’t quite what’s happening. They make it look like Roslyn deletes the entirety of your source code, but it really doesn’t. It just deletes the two files that were created as part of the bundling.

watch

The watch command will tell Roslyn to watch all of the files that you marked as input files (in your bundleconfig.json file). Each time that you save a change to ANY of those input files, Roslyn will rerun the bundle command.

Here is how you run the watch command:

I’ll explain why we ran the bundle command first, in a moment.

Which will produce output similar to this:

The highlighted lines show what happened when I saved a change to my site.css file.

One important caveat for this command is that you’ll need to have created the bundles before it can be run successfully (which is why we ran dotnet bundle first). If the bundled files cannot be found (i.e. site.min.css), then overwriting them will fail.

This can be hard to debug, because the error message isn’t that helpful:

So be aware of that.

Another way to avoid this is to build you application (earlier, we ran the bundle command), this will ensure that bundling happens (if it’s set as a precompile action in your project.json) and that the bundled files are saved to disk before the watch command attempts to access them.

Using The Bundles In Your Markup

Referencing the bundles in your markup is pretty easy, as you just have to use the tilde (~) accessor in the path to the file containing the bundle.

Here’s an example of what I mean, taken from my _layout.cshtml (with a lot of stuff stripped out):

I’ve highlighted the lines where I’m using the tilde operator

You’ll also notice that I’m using the minified CSS and JS in staging and production only. This is pretty good practise for debugging your CSS and JS – especially if you decline to add source maps to your bundle objects – as breakpoints wont work so well in JS debuggers when there isn’t a source map present.

Conclusion

Adding BundlerMinifier.Core to a .NET Core MVC project is pretty easy to do, and getting Roslyn to use the bundleconfig.json (to actually) do the bundling is pretty simple too.

To find out more about BundlerMinifier (and how to use it in Visual Studio), head over to it’s GitHub page.

But why is BunclerMinifier.Core the default option for a new .NET Core a Web Application project via Yeoman? Well, you’ll have to wait until next week to find out.

Unless you’re a keen web searcher, that is.