JavaScript and CSS Minifier

Introduction

The CombineAndMinify package discussed here automatically speeds up the loading of JavaScript files, CSS files and or images (loaded from image tags or from CSS files). The result can be a dramatic improvement in ASP.NET performance.

Installation is easy - just add a dll, update your web.config and add a small file. If you use IIS 6, you'll also need to update the configuration of IIS (no such update needed for IIS 7). Step by step installation instructions are in the installation section.
Download

Requirements

• ASP.NET 3.5 or higher
• IIS 6 or higher for your live site

Features

The features below can all be switched on and off individually via the web.config file (full description). If you just install the package and not do any further configuration, it only minifies and combines JavaScript and CSS files, and than only when the site is in Release mode.

Although the feature set below is extensive, there are many more ways to improve ASP.NET performance. My recently released book ASP.NET Site Performance Secrets shows how to pinpoint the biggest performance bottlenecks in your web site, using various tools and performance counters built into Windows, IIS and SQL Server. It then shows how to fix those bottlenecks. It covers all environments used by a web site - the web server, the database server, and the browser. The book is extremely hands on - the aim is to improve web site performance today, without wading through a lot of theory first.

CombineAndMinify features:

• Minifies JavaScript and CSS files. Minification involves stripping superfluous white space and comments. Only JavaScript and CSS files that are loaded from the head sections of your pages are minified.
  
• Correctly processes files that contain non-English text such as Chinese. The package uses the efficient YUI minifier to minify JavaScript and CSS files that are all in English (that is, contain only ASCII characters). Because the YUI minifier doesn't handle non-ASCII characters (such as Chinese), the package automatically uses the JSMIN algorithm for files containing such characters. JSMIN is less efficient, but handles non-ASCII characters well.
  
• Combines JavaScript files and CSS files. Loading a single large file is often much quicker than loading a series of small files, because that saves the overhead involved in all the request and response messages.
  
  If a CSS file contains image urls that are relative to the folder containing the CSS file itself, those urls are fixed up by the package. That way, they continue to work even if CSS files from several different folders are combined.
  
• Allows you to configure the package so it only kicks in in release mode. That way, you see your individual files complete with white space and comments while developing, and reap the performance improvement in your live site.
  
• Reduces the size of the HTML generated by your .aspx pages by removing white space and comments. Note that the .aspx files themselves are not affected, only the HTML sent to the browser.
  
• Allows you to configure cookieless domains from which to load JavaScript files, CSS files and images. This way, the browser no longer sends cookies when it requests those files, reducing wait times for the visitor.
  
• Lets you configure multiple cookieless domains. This causes the browser to load more JavaScript, CSS and image files in parallel.
  
• Optimizes use of the browser cache by allowing the browser to store JavaScript, CSS and image files for up to a year. Uses version ids in file names to ensure the browser picks up new versions of your files right away, so visitor never see outdated files (details on how this works).
  
• Unlike similar packages, doesn't add query strings when combining files or when inserting versions. This optimizes caching by proxy servers (many proxy servers won't cache files with query strings).
  
• Converts image file names to lower case, to make it easier for those proxy and browser caches that do case sensitive file name comparisons to find your file in their caches - so they don't request the same file again.
  
• Preloads images immediately when the page starts loading, instead of when the browser gets round to loading the image tags - so your images appear quicker. You can give specific images priority.
  
• Helps you detect missing files by throwing an exception when a JavaScript file, CSS file or image is missing. By default, the package handles missing files silently, without throwing an exception.
  
• To reduce CPU overhead and disk accesses caused by the package, it caches intermediate results, such as minified files. A cache entry is removed when the underlying file is changed, so you'll never serve outdated files.

Server compression

If you are interested in web site performance, you may be interested in this short digression into server compression.

IIS 6 and 7, and Apache as well, provide the option to gzip compress all text files (html, JavaScript, CSS, etc.) sent to the browser. All modern browsers know how to decompress those files. Compression can save you a lot of bandwidth and download time. It is not uncommon to reduce file sizes by way over 50%.

In IIS, compression is switched off by default for dynamic files, such as .aspx files. This is because it increases the load on the CPU. However, with the overabundence of CPU cycles on modern server hardware, switching on compression for dynamic files on your server is almost always a great idea. Also, IIS 6 and 7 allow you to set the compression level, so you can choose a level that you're comfortable with. Finally, IIS 7 can automatically switch off compression when CPU usage goes over a predetermined level (set by you), and switch it back on after CPU usage has dropped below a second level (also set by you). It even lets you cache compressed dynamic files, which makes compression extremely attractive.

Switching on basic compression on IIS 7 is easy, but getting the most out of it is a bit tricky. Switching on compression in IIS 6 is just tricky. Good places to find out more would be here (for IIS 7) and here (for IIS 6).

Or you could read chapter 10 of my book ASP.NET Site Performance Secrets where it is all spelt out in one place (believe me, this will save you a lot of time).

Installation

Installing the CombineAndMinify package involves these steps:

1. Common installation - applies to all environments.
2. IIS 7 related - only applies if your live site runs under IIS 7.
3. IIS 6 related - only applies if your live site runs under IIS 6.
4. Development environment related - only applies if you want to use the package not just in your live site, but also in your development environment.

Common Installation

1. Compile the package:
   
   • Download the zip file with the source code, and unzip in a directory.
   • Open the CombineAndMinify.sln file in Visual Studio 2008 or later.
   • You'll find that the sources are organized in a solution, with these elements:
     
     1. Project CombineAndMinify is the actual package.
     2. Web site Testsite contains a lot of (functional but rather disorganised) test cases. Ignore this unless you want to test the package.
     
   • Compile the solution. This will produce a CombineAndMinify.dll file in the CombineAndMinify\bin folder.
2. Update your web site:
   
   1. Add a reference to CombineAndMinify.dll to your web site (in Visual Studio, right click your web site, choose Add Reference)
   2. Add the custom section combineAndMinify to your web.config:
   
   <configuration>
   ...
   <configSections>
   ...
   <section name="combineAndMinify" type="CombineAndMinify.ConfigSection"/>
   ...
   </configSections>
   ...
   </configuration>
   
3. Allow the package to process the head sections of your pages. That way, it can replace the tags loading individual JavaScript and CSS files with tags loading combined files:
   
   1. Make sure that the head tags of your pages have runat="server", like so:
   
   <head runat="server">
   
   When you create a new page in Visual Studio, it creates a head section with runat="server", so you probably don't have to change anything here.
   
   2. Add a folder called App_Browsers to the root folder of your web site.
   
   3. Use your favorite text editor (such as Notepad) to create a text file in the App_Browsers folder. Call it HeadAdapter.browser. Into that file, copy and paste this code:
   
   <browsers>
   <browser refID="Default">
   <controlAdapters>
   <adapter controlType="System.Web.UI.HtmlControls.HtmlHead"
   adapterType="CombineAndMinify.HeadAdapter" />
   </controlAdapters>
   </browser>
   </browsers>
   
   This tells ASP.NET to leave processing of all HtmlHead controls (which represent the head tags) to the class CombineAndMinify.HeadAdapter (which is part of the package).
   
4. Make sure that your site has trust level Full. This allows it to access the combineAndMinify section. If your web.config contains
   
   <trust level=... />
   
   remove it. You'll than get the default trust level, which is Full.

IIS 7

Only do these steps if you use IIS 7 for your live site or your development environment. If you only use IIS 6 or IIS 7 in classic mode, skip to the IIS 6 section.

The package uses an HTTP Handler to combine and minify JavaScript and CSS files on the fly. To reduce CPU overhead, it caches the combined files, so they only get combined and minified after they have been changed on the file system.

To configure the HTTP Handler, add the following to your web.config:

</configuration>
...
<system.webServer>
<validation validateIntegratedModeConfiguration="false"/>
...
<handlers>
...
<add name="JavaScriptHandler" verb="*" path="*.js" type="CombineAndMinify.HttpHandler, CombineAndMinify" resourceType="Unspecified"/>
<add name="CssHandler" verb="*" path="*.css" type="CombineAndMinify.HttpHandler, CombineAndMinify" resourceType="Unspecified"/>
</handlers>
...
</system.webServer>
...
</configuration>

IIS 6

Only do these steps if you use IIS 6 or IIS 7 in classic mode. If you use IIS 7, do the installation for IIS 7. If you want to invoke the package not only in your live environment but your development environment as well, than do the installation related to your development environment as well.

1. Configure the HTTP Handler in your web.config:

<configuration>
...
<system.web>
...
<httpHandlers>
...
<add verb="*" path="*.js" type="CombineAndMinify.HttpHandler, CombineAndMinify" />
<add verb="*" path="*.css" type="CombineAndMinify.HttpHandler, CombineAndMinify" />
</httpHandlers>
...
</system.web>
...
</configuration>

2. Send all requests for JavaScript and CSS files to the ASP.NET handler. That allows the package to combine and minify them.

• Open the IIS Manager - click Start | Administrative Tools | Internet Information Services (IIS) Manager.
• Expand your server. Expand Web Sites. Right click your web site and choose Properties.
• Click the Home Directory tab, and then click the Configuration button.
• Get the path to the ASP.NET handler:
  
  1. Click the line with the .aspx extension.
  2. Click the Edit button.
  3. Copy the contents of the Executable box. If you use .Net 2 or .Net 3.5, it will be C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll.
  
  4. Click Cancel to dismiss the dialog.
  5. Tell IIS 6 to let ASP.NET handle all requests for files with extension .js:
  
  • Click the Add button.
  • Paste the path to the ASP.NET handler you just found into the Executable field.
  • Enter .js into the Extension field.
  • Uncheck the Verify that file exists box.
  • Click OK.
  • Repeat the last step, but now for extension .css.
  • Click OK to dismiss the Configuration dialog.
  • Click the Apply button, and then click OK to dismiss the Properties dialog.

Development Environment

By default, the package is only active when your site is in Release mode - that is, if you have

<compilation debug="false">

in your web.config. That makes sense, because the package doesn't affect the functionality of your site - it just makes it faster. If this arrangement works for you, there is no need to do any installation related to your development environment, so you can skip this section.

If you do want to activate the package in your development environment, you need to run your debugging sessions under IIS 7, instead of under Cassini (the web server that normally runs when you hit F5 in Visual Studio). This is because the package uses an HTTP Handler to process JavaScript and CSS files, and Cassini in .Net 3.5 doesn't support HTTP Handlers.

Note that IIS 7 is included in the Home Premium, Business, Enterprise and Ultimate versions of Windows Vista and Win 7 (but not the Starter and Home versions). That means you probably already have it on your system.

Here is how to run your debugging sessions under IIS 7:

1. Install IIS 7 on your development machine
2. Create a development site in IIS 7
3. Get Visual Studio to use IIS 7 instead of Cassini
4. Do the installation steps related to IIS 7
5. Make sure the package is active in debug mode

Let's go through these steps one by one.

1. Install IIS 7 on your development machine

• Click Start | Control Panel | Programs | Turn windows features on or off.
• Check Internet Information Services.
• Expand the Internet Information Services node, expand Web Management Tools and make sure IIS Management Console is checked. This will allow you to run the IIS Manager.
• Expand IIS 6 Management Compatibility and make sure IIS Metabase and IIS 6 configuration compatibility is checked. You need this to be able to use IIS from Visual Studio.
• Expand the World Wide Web Services node and then the Application Development Features node. Make sure that ASP.NET is checked, so the server can run ASP.NET applications.
• Also under World Wide Web Services, expand Security and make sure Windows Authentication is selected. You need this to be able to use IIS from Visual Studio.
• Click OK. Windows will take a while to implement the changes.

2. Create a development site in IIS

Now that you have installed IIS 7 on your machine, create a site in IIS 7 that Visual Studio can use for debugging sessions:

• While still in IIS Manager, expand your machine. Right click Sites and choose Add Web Site. The Add Web Site dialog opens.
• Make up a site name. As the physical path, enter the root folder of your source files – the one with default.aspx and web.config. Enter a port that isn't already in use, for example 1080. Click OK.
• Enable Windows Authentication. Double click your new site, double click Authentication, right click Windows Authentication and choose Enable.

3. Get Visual Studio to use IIS 7 instead of Cassini

If you use a Web Site:

• Run Visual Studio as administrator. Right click your web site and choose Start Options. The Property Pages window opens, with the Start Options tab selected.
• In the Server section, select Use custom server. In the Base Url field, enter the localhost address with the port you entered when you created the development site in IIS manager - for example http://localhost:1080.
• Click OK.

If you use a Web Application:

1. In Visual Studio, right click the web application and choose Properties. The properties window opens.
2. Click the Web tab.
3. Scroll down to the Servers section and select Use Local IIS Web server. In the Project Url field, enter the localhost address with the port you entered when you created the development site in IIS manager.
4. Save the properties.

Now when you hit F5 in Visual Studio to run your site in debug mode, you'll find it runs under IIS 7 instead of under Cassini. Apart from that, your debugging experience is the same - you can still set breakpoints, etc.

4. Do the installation steps related to IIS 7

Now that you're using IIS 7 to do development, do the IIS 7 related installation if you have not already done that.

5. Make sure the package is active in debug mode

Follow the steps listed here.
Configuration

By default, the package minifies and combines JavaScript and CSS files. To use the other features, or to switch off minification or combining of JavaScript or CSS files, add a combineAndMinify element to your web.config file, like so:

<configuration>
...
<combineAndMinify ... >

</combineAndMinify>
...
</configuration>

The combineAndMinify element supports these attributes and child elements:

• active
• combineCSSFiles
• combineJavaScriptFiles
• minifyCSS
• minifyJavaScript
• cookielessDomains
• enableCookielessDomains
• preloadAllImages
• prioritizedImages
• makeImageUrlsLowercase
• insertVersionIdInImageUrls
• exceptionOnMissingFile
• removeWhitespace
• headCaching

active

Determines when the package is active. When it is not active, it doesn't affect your site at all and none of the other attributes or child elements listed in this section have any effect.

Example

<configuration>
...
<combineAndMinify active="Always" >

</combineAndMinify>
...
</configuration>

Whether your site is in debug or release mode depends on the debug attribute of the compilation element in your web.config file. If that attribute is set to false, your site is in release mode (as it should be when live). When it is set true, it is in debug mode (as it should be in development). It looks like this in web.config:

<configuration>
...
<system.web>
<compilation debug="true">
...
</compilation>
...
</system.web>
...
</configuration>

Note that by default, the package is only active in release mode - so you won't see any effect while you're developing. To ensure that the package is active in both release mode and in debug mode as well, set active to Always, as shown in the example above.

Note that the active attribute acts as a master switch for the whole package. It's like the ignition in a car - if you don't turn on the ignition (or at least the battery), pressing any other buttons on the dashboard won't do anything.

combineCSSFiles

Determines whether the package combines CSS files.

Example

<configuration>
...
<combineAndMinify combineCSSFiles="All" >

</combineAndMinify>
...
</configuration>

To see what is meant with "per group", have a look at this example:

<link rel="Stylesheet" type="text/css" href="/css/site1.css" />
<link rel="Stylesheet" type="text/css" href="/css/site2.css" />

<script type="text/javascript" src="js/script1.js"></script>

<link rel="Stylesheet" type="text/css" href="/css/site3.css" />
<link rel="Stylesheet" type="text/css" href="/css/site4.css" />

By default, the package tries to ensure that the order of the JavaScript and CSS definitions doesn't change when JavaScript and CSS files are combined. It does this by grouping CSS files whose tags are after each other. In this case, there are 2 groups - site1.css and site2.css, and site3.css and site4.css. This causes the browser to load the CSS and JavaScrip definitions in the exact same order as when the files had not been combined:

1. Combined file with all CSS definitions in site1.css and site2.css
2. script1.js
3. Combined file with all CSS definitions in site3.css and site4.css

You get this behaviour when you set combineCSSFiles to PerGroup (which is the default). The package supports grouping for JavaScript files as well, which is controlled by the combineJavaScriptFiles attribute.

Combining all CSS files into one file

If you set combineCSSFiles to All, all CSS files get combined into a single file. The link tag to load that combined CSS file gets placed where the link tag of the first CSS file used to be. In our example, that causes this load order:

1. Combined file with all CSS definitions in site1.css, site2.css, site3.css and site4.css
2. script1.js

As you see, the CSS definitions in site3.css and site4.css now get loaded before script1.js, instead of after script1.js. As a result, the number of CSS files that need to be loaded is reduced from two to one (as compared with grouping), but you also change the order in which CSS and JavaScript definitions are loaded. It depends on your site whether that is an issue or not.

Loading CSS files from another site

If you decide to set combineCSSFiles to All, be sure that your site doesn't load CSS files from another web site. This is uncommon, but if yours is one of the rare sites that does this, consider this example:

<link rel="Stylesheet" type="text/css" href="/css/site1.css" />
<link rel="Stylesheet" type="text/css" href="/css/site2.css" />

<link rel="Stylesheet" type="text/css" href="http://anothersite.com/css/other.css" />

<link rel="Stylesheet" type="text/css" href="/css/site3.css" />
<link rel="Stylesheet" type="text/css" href="/css/site4.css" />

The package never combines CSS files from other sites - not with CSS files from your site, not with CSS files from the other site. As a result, if you change combineCSSFiles to All, the package will combine all CSS files loaded from your site (but not those from the other site), causing the following load order:

1. Combined file with all CSS definitions in site1.css, site2.css, site3.css and site4.css
2. http://anothersite.com/css/other.css

The definitions in other.css now came after those in site3.css and site4.css, meaning they may take precedence - which could break your CSS.

combineJavaScriptFiles

Determines whether the package combines JavaScript files.

Example

<configuration>
...
<combineAndMinify combineJavaScriptFiles="All" >

</combineAndMinify>
...
</configuration>

As you saw in the description of combineCSSFiles, the package groups JavaScript files in the same way as CSS files. Similarly, if you set combineJavaScriptFiles to All, all JavaScript files that are loaded from your site get combined into a single JavaScript file.

However, there is one major difference with combining CSS files: When you combine all JavaScript files into a single file (combineJavaScriptFiles is All), the script tag for the combined file winds up at the location where the last original script tag used to be. This in contract to a combined CSS file, which winds up at the location of the first original CSS tag.

This makes life easier if you load JavaScript libraries from extenal sites. If you use a popular package such as jQuery, you can load it from the free Google Content Delivery Network (CDN) and also from the free Microsoft CDN - which saves you bandwidth and download time (details about those CDNs are in chapter 13 of my book).

Take this example:

<script type="text/javascript" src="/js/script1.js" ></script>
<script type="text/javascript" src="/js/script2.js" ></script>

<!-- load jQuery from free Google CDN -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

<script type="text/javascript" src="/js/script3.js" ></script>
<script type="text/javascript" src="/js/script4.js" ></script>

script3.js and script4.js may well be dependent on jquery.min.js. If combineJavaScriptFiles is set to PerGroup, you wind up with this load order: