ASP.NET Hosting - Click Here!

Bundling allows you to group and compress files of the same type to increase performance.

Available on a separate extension

For the past couple of years, Web Essentials have been including features for bundling and minifying JS and CSS files. As of Web Essentials 2015 that is no longer the case. However, this feature is still available with a new stand alone Visual Studio 2015 extensions.

You can find more details about the why and how of this extension on this blog post or you can download it from here.

This new extension is not an extract of the Web Essentials 2013 bundling feature but a complete new one. So you will have to recreate your .bundle files on the Bundler & Minifier .json format but the mapping is easy to do.

What is a bundle?

A Web Essentials bundle file is a recipe for grouping, and usually compressing, a set of files of the same type to limit the number and the amout the data to be downloaded by the browser.

Web Essentials offers two bundling types:

  1. .bundle : for CSS and JS files

    For CSS, it outputs a XML bundle recipe file, a destination CSS file and a minified version of source if you turn on the minify option on the recipe.

    For JavaScript files, it outputs a destination JS file, a minified version of sources and a source-map of that min.

  2. .sprite : for images (PNG, JPG and GIF). It generates a sprite image, CSS with example code for all the possible coordinates in background property, LESS and SASS files with mixins holding the same background properties and a custom map file (JSON) with all those coordinates.

How to make a bundle?

The procedure to create a bundle is the same for all types of files.

  • On the Solution Explorer, select files that you want to bundle together.
  • On the Web Essentials context menu, pick Create image sprite... or Create CSS/JS bundle file depending on your context.
  • Specify a name for the bundle file.

How it works?

Basically, there are two ways to update bundled assets.

  1. Changing an ingredient, such as .js, .css or image.
  2. Updating a bundle recipe file.
When a recipe is saved, recreate bundle RECIPE INGREDIENTS When any ingredient is changed, recreate all bundles containing this asset BUNDLED ASSET JS CSS HTML Images

Example files

Generated XML files are well self-documented. Here are examples for both types of files to give you a better idea of the available features.

Bundle

<?xml version="1.0" encoding="utf-8"?>
<bundle xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="http://vswebessentials.com/schemas/v1/bundle.xsd">
  <settings>
    <!--Determines if the sprite image should be automatically optimized after creation/update.-->
    <minify>true</minify>
    <!--Determine whether to generate/re-generate this sprite on building the solution.-->
    <runOnBuild>false</runOnBuild>
    <!-- Use absolute path in the generated CSS files. By default, the URLs are relative to generated 
         bundled CSS file.-->
    <adjustRelativePaths>true</adjustRelativePaths>
    <!-- Specifies a custom subfolder to save files to. By default, compiled output will be placed 
         in the same folder and nested under the original file.-->
    <outputDirectory />
  </settings>
  <!--The order of the <file> elements determines the order of the images in the bundle.-->
  <files>
    <file>/Content/bootstrap.css</file>
    <file>/Content/Site.css</file>
  </files>
</bundle>

Sprite

<?xml version="1.0" encoding="utf-8"?>
<sprite xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="http://vswebessentials.com/schemas/v1/sprite.xsd">
  <settings>
    <!-- Determines if the sprite image should be automatically optimized after creation/update. -->
    <optimize>true</optimize>
    <!-- Determines the orientation of images to form this sprite. The value must be vertical or 
         horizontal. -->
    <orientation>vertical</orientation>
    <!-- The margin (in pixel) around and between the constituent images. -->
    <margin>1</margin>
    <!-- File extension of sprite image. -->
    <outputType>jpg</outputType>
    <!-- Determine whether to generate/re-generate this sprite on building the solution. -->
    <runOnBuild>false</runOnBuild>
    <!-- Use full path to generate unique class or mixin name in CSS, LESS and SASS files. 
         Consider disabling this if you want class names to be filename only. -->
    <fullPathForIdentifierName>true</fullPathForIdentifierName>
    <!-- Use absolute path in the generated CSS-like files. By default, the URLs are relative to 
         sprite image file (and the location of CSS, LESS and SCSS). -->
    <useAbsoluteUrl>false</useAbsoluteUrl>
    <!-- Specifies a custom subfolder to save files to. By default, compiled output will be 
         placed in the same folder and nested under the original file. -->
    <outputDirectory />
    <!-- Specifies a custom subfolder to save CSS files to. By default, compiled output will be 
         placed in the same folder and nested under the original file. -->
    <outputDirectoryForCss />
    <!-- Specifies a custom subfolder to save LESS files to. By default, compiled output will be 
         placed in the same folder and nested under the original file. -->
    <outputDirectoryForLess />
    <!-- Specifies a custom subfolder to save SCSS files to. By default, compiled output will be 
         placed in the same folder and nested under the original file. -->
    <outputDirectoryForScss />
  </settings>
  <!-- The order of the <file> elements determines the order of the images in the sprite. -->
  <files>
    <file>/Content/img/arrow1.jpg</file>
    <file>/Content/img/arrow2.png</file>
    <file>/Content/img/arrow3.png</file>
  </files>
</sprite>

Known behaviors

General

  • When you generate a bundle for a directory, the list of files comes from the file-system, not from the Visual Studio project. So, if the directory contains some files not included in your project, they will be included in your sprite. To prevent that, you just have to select all files manually instead of the directory.