CSS optimizations

The Aggregator provides a CSS module builder for building/minifying CSS files. The CSS module builder performs the following optimizations on CSS resources (resources who's module names end with .css):

• White-space and comment removal
• Optional execution of configured PostCss plugins (provided that the plugin runs in Rhino).
• Optional inlining of image references using the Data URI Scheme
• Optional inlining of CSS files imported using the @import statement

Applications can use the CSS Loader Plug-in to load CSS files using AMD.

CSS module builder config properties

Various options and parameters for controlling the behavior of the CSS module builder are specified using properties in the Server-Side AMD config file. The following config properties are recognized by the CSS module builder:

Name	Description
inlineCSSImports	If the value of this property is "true", then the CSS module builder will recursively inline CSS modules that are imported using the @import directive and perform the necessary rewriting of relative URLs.  The default value is false.
inlinedImageSizeThreshold	If the value of this property is an integer value greater than zero, it specifies the maximum size of image references to inline using the Data URI Scheme.  The default value is zero.
inlineableImageTypes	This property specifies a comma separated list of image types (mime types) to inline.  The standard image types image/gif, image/jpeg, image/png and image/tiff are included by default and do not need to be specified here.  If you wish additional image types to be inlined, then you must specify them here. **New in 1.2.** This property may be specified as a map of file-extension/mime-type pairs. For example: ``` inlineableImageTypes:{ svg:'image/svg+xml', bmp:'image/bmp' } ``` This allows the use of image types not known by the platform.
inlinedImageIncludeList	A comma separated list of image names (may include the '?' and '*' wildcard characters) listing the names of images that should be inlined.  If this config property is specified, then only images listed in this list that are not also listed in inlinedImageExcludeList will be inlined.
inlinedImageExcludeList	A comma separated list of image names (may include the '?' and '*' wildcard characters) listing the names of images that should not be inlines.  Any images listed here will not be inlined, regardless of whether or not they satisfy any of the other conditions specified above.
postcss	An object map containing a `plugins` property who's value consists of a two-dimensional array of module-id/initialization-function pairs. Each array element specifies and initializes one postCss plugin that will be run against CSS modules. The module-id is an AMD module identifier relative to the baseUrl, paths and/or packages defined in the config, or else an absolute URI to a module located on the server. The initialization function is passed a reference to the loaded module and returns the postCss plugin instance that will be invoked to process the CSS. In the simple case that the module is the plugin, then the initialization function will simply return the module reference. The following example shows how you might initialize the autoprefixer plugin to support the last two browser versions of popular browsers: ``` postcss: { plugins: [ [ 'plugins/autoprefixer-core', function(autoprefixer) { return autoprefixer({ browsers: ['last 2 versions'] }).postcss; } ] ] }, ``` Modules should be [browserified](http://browserify.org/) (i.e. be self-contained with no external dependencies) as the use of the CommonJS `require()` function to load module dependencies on the server is not currently supported. This property was introduced in version 1.2.2.

Performance considerations

Inlining of image references in CSS can improve web application performance by reducing the number of HTTP requests needed to load the application, but it must be used with care because if mis-used, it can negatively impact performance by bloating the size of the CSS. In particular, image sprites should never be inlined. Image sprites are used to leverage browser caching by allowing multipe images to be loaded and cached with a single HTTP request. Since inlining of image references in CSS reproduces the image data within the CSS each time the image is referenced, it is virtually always better to load image sprites separately than to inline them. The best candidates for inlining are small images that are referenced infrequently. The config properties discussed above are designed to provide enough flexibility in controlling which images will be inlined and which won't so that you can fine-tune the performance of your application. Another consideration when deciding whether or not to make use of image reference inlining is that some older browsers may not fully support inlining of images in CSS files.

Inlining of imported CSS files using the @import directive is provided mostly for legacy code that uses a monolithic CSS file, importing all the styles for the application (e.g. dijit theme files such as tundra.css). AMD applications are encouraged to specify styles in module specific CSS files that are 'required' by the JavaScript modules for the widgets that reference those styles.