JavaScript and CSS Minifier


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.


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


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).


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:

    <section name="combineAndMinify" type="CombineAndMinify.ConfigSection"/> 
  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:

    <browser refID="Default">
    <adapter controlType="System.Web.UI.HtmlControls.HtmlHead"
    adapterType="CombineAndMinify.HeadAdapter" />

    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.