Combine CSS

Configuration

The 'Combine CSS' filter is enabled by specifying:

Apache:

ModPagespeedEnableFilters combine_css

Nginx:

pagespeed EnableFilters combine_css;

in the configuration file.

Description

'Combine CSS' seeks to reduce the number of HTTP requests made by a browser during page refresh by replacing multiple distinct CSS files with a single CSS file, containing the contents of all of them. This is particularly important in old browsers, that were limited to two connections per domain. In addition to reduced overhead for HTTP headers and communications warm-up, this approach works better with TCP/IP slow-start, increasing the effective payload bit-rate through the browser's network connection.

This practice reduces the number of round-trip times.

Operation

The "CSS Combine" filter finds all CSS <link> tags. If there was more than one in a flush window, it removes each of those links and replaces them with a single <link> to the merged document, which it places wherever the first CSS <link> originally was.

For example, if the HTML document looks like this:

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="styles/yellow.css">
    <link rel="stylesheet" type="text/css" href="styles/blue.css">
    <link rel="stylesheet" type="text/css" href="styles/big.css">
    <link rel="stylesheet" type="text/css" href="styles/bold.css">
  </head>
  <body>
    <div class="blue yellow big bold">
      Hello, world!
    </div>
  </body>
</html>

Then PageSpeed will rewrite it into:

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="styles/yellow.css+blue.css+big.css+bold.css.pagespeed.cc.xo4He3_gYf.css">
  </head>
  <body>
    <div class="blue yellow big bold">
      Hello, world!
    </div>
  </body>
</html>

Example

You can see the filter in action at www.modpagespeed.com on this example.

Parameters that affect CSS optimization

MaxCombinedCssBytes

Apache:

ModPagespeedMaxCombinedCssBytes MaxBytes

Nginx:

pagespeed MaxCombinedCssBytes MaxBytes;

MaxBytes is the maximum size in bytes of the combined CSS files. CSS files larger than MaxBytes will be kept intact; other CSS files will be combined into one or more files, each being no more than MaxBytes in size. The current default value for MaxBytes is -1 (unlimited).

Limitations

The CSS Combine filter operates within the scope of a "flush window". Specifically, large, or dynamically generated HTML files may be "flushed" by the resource generator before they are complete. When the CSS combiner encounters a flush, it will emit all CSS combinations seen up to the point of the flush. After the flush, it will begin collecting a new CSS combination.

This filter generates URLs that are essentially the concatenation of the URLs of all the CSS files being combined. The maximum URL size is generally limited to about 2k characters due to IE: See http://support.microsoft.com/kb/208427/EN-US. Apache servers by default impose a further limitation of about 250 characters per URL segment (text between slashes). PageSpeed circumvents this limitation when it runs within Apache, but if you employ proxy servers in your path you may need to re-impose it by overriding the setting here. The default setting is 1024.

Apache:

ModPagespeedMaxSegmentLength 250

Nginx:

pagespeed MaxSegmentLength 250;

Combining Resources with IDs

Note: New feature as of 1.12.34.1

By default PageSpeed won't combine CSS files that have id attributes, because this often indicates that the site designer intended to reference them in javascript. However, some content management systems, including WordPress, put ids on all stylesheets for clarity. To enable combining these files, you can provide one or more wildcards. For example, this would mark stylesheets with ids starting with font as eligible for combining:

Apache:

ModPagespeedPermitIdsForCssCombining font*

Nginx:

pagespeed PermitIdsForCssCombining font*;

Requirements

The 'Combine CSS' filter may need to absolutify relative URLs, if rewriting the CSS causes the path to be moved. The filter will not merge together resources from multiple distinct domains, even if those domains are each authorized by Domain. It will merge together resources from multiple distinct domains that have been mapped together via MapRewriteDomain.

By default, the filter will combine together CSS files from different paths, placing the combined element at the lowest level common to both origins. In some cases, this may be undesirable. You can turn off the behavior with:

Apache:

ModPagespeedCombineAcrossPaths off

Nginx:

pagespeed CombineAcrossPaths off;

The filter will maintain the order of the CSS contents, as class order can be significant.

IE Directives containing CSS links form a "barrier" for the CSS combiner. Multiple CSS elements found before an IE directive are combined together immediately before the IE directive. Multiple CSS elements found after are also combined, but the combination does not span across the IE directive, as that would affect the order that the browser sees the CSS elements.

Risks

This filter is considered low risk. However, JavaScript can be written that walks the DOM looking for <link> entries with certain syntax. Such JavaScript may behave differently on a page which has modified CSS links in this way.