Combine JavaScript

Configuration

The 'Combine JavaScript' filter is enabled by specifying:

Apache:

ModPagespeedEnableFilters combine_javascript

Nginx:

pagespeed EnableFilters combine_javascript;

in the configuration file.

Description

'Combine JavaScript' seeks to reduce the number of HTTP requests made by a browser during page refresh by replacing multiple distinct JavaScript files with a single one.

This practice reduces the number of round-trip times.

Example

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

Parameters that affect JS combining

MaxCombinedJsBytes

Apache:

ModPagespeedMaxCombinedJsBytes MaxBytes

Nginx:

pagespeed MaxCombinedJsBytes MaxBytes;

MaxBytes is the maximum uncompressed size in bytes of the combined JavaScript files. JavaScript files larger than MaxBytes will be kept intact; other JavaScript files will be combined into one or more files, each being no more than MaxBytes in size. The current default value for MaxBytes is 92160 (90K).

Limitations

The JavaScript 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 filter encounters a flush, it will emit all script combinations seen up to the point of the flush. After the flush, it will begin collecting a new script combination.

This filter currently cannot combine across inline scripts, and IE conditional comments.

This filter generates URLs that are essentially the concatenation of the URLs of all the Javascript 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 under 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;

Requirements

By default, the filter will combine together script 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;

Risks

This filter is considered moderate risk. However, JavaScript can be written that walks the DOM looking for <script> entries with certain syntax. Such JavaScript may behave differently on a page which has modified script locations and structure.

This filter is sensitive to AvoidRenamingIntrospectiveJavascript. For example, a JavaScript file that calls document.getElementsByTagName('script') will not be combined with other JavaScript files.

This filter employs the Javascript 'eval' expression to evaluate each <script> tag at its proper location in the DOM, but getting the aggregated script content in one HTTP fetch. The effects of this are likely to differ between browsers, and haven't yet been thoroughly measured.