Flatten CSS Imports

Configuration

The 'Flatten CSS Imports' filter is enabled by specifying:

Apache:
ModPagespeedEnableFilters flatten_css_imports
Nginx:
pagespeed EnableFilters flatten_css_imports;

in the configuration file.

When this filter is enabled, you may also enable the following setting:

Apache:
ModPagespeedCssFlattenMaxBytes bytes
Nginx:
pagespeed CssFlattenMaxBytes bytes;

This is the maximum size in bytes of the flattened CSS; if flattening would result in CSS larger than this then flattening will be aborted and the CSS will be left unchanged.

Objective

Reduce the number of HTTP round-trips by combining multiple CSS resources into one.

PageSpeed Rule

This filter implements the PageSpeed rule for avoiding CSS imports.

Description

flatten_css_imports parses linked and inlined CSS and flattens it by replacing all @import rules with the contents of the imported file, repeating the process recursively for each imported file. It works on CSS found in <style> blocks and <link> references.

Operation

flatten_css_imports recursively processes imported CSS files; if a file cannot be processed then the entire process is aborted and the initial CSS is left unflattened.

The CSS is processed as follows; if any step fails the entire process is aborted and the CSS is left unflattened:

  1. The CSS is parsed; if there are any errors while parsing @import rules, this step fails.
  2. The CSS is checked for any leading @charset rule; if there is one and the specified character set is not the same as the current one then this step fails.
  3. All @import rules are removed and the specified files are fetched and processed recursively and each removed @import rule is replaced with its file's flattened contents; if a file cannot be fetched for any reason this step fails.
  4. Any rulesets following the @import rules are appended.
  5. The resulting CSS is minified; if it can't be minified this step fails.
  6. The size of the resulting CSS is checked against the configured maximum for flattened CSS; if it is too big this step fails.
  7. Finally, the original <style> or <link> is replaced with the minified CSS.

The initial charset is determined according to the rules for HTTP: from the HTML's response headers if any, otherwise from the charset attribute of the <link> element if any, otherwise it defaults to ISO-8859-1.

@import rules can specify the media type(s) that apply to the imported file, and the initial <style> or <link> element can also specify the applicable media types. flatten_css_imports remembers the "containing" media types and if an @import specifies media types it applies the intersection of the containing and specified media types to the imported file; if this is empty then the file is ignored because it cannot apply. This is only done for simple media types, not media expressions. If a flattened file has any media types other than all then its rulesets are wrapped in an appropriate @media rule.

Example

The effect of this filter can be observed on modpagespeed.com before and after rewriting.

Requirements

The rewrite_css filter must be enabled for this filter to be applied.

Limitations

Only CSS referenced by <style> and <link> tags is rewritten. style attributes of HTML elements are not rewritten.

Not all CSS3 or proprietary constructs are parsed. When unhandled syntax is present and the file cannot be parsed completely, the CSS file is left unflattened.

Risks

flatten_css_imports is considered moderate risk because it makes the fairly complex media optimization described above.