Flatten CSS Imports

PageSpeed Service was turned off on August 3rd, 2015. Please see Turndown Information for PageSpeed Service.

Objective

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

PageSpeed Rule

This rewriter 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 rewriter can be observed on pssdemos.com before and after rewriting.

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.

If the flattened CSS would be more than 2048 bytes the flattening process will be aborted because beyond this point performance can be worse than when not flattened.

Risks

Flatten CSS Imports is considered moderate risk because it makes the fairly complex media optimization described above.