JavaScript Filters

Overview

mod_pagespeed 1.1 includes filters for JavaScript minification, combining, inlining, and deferring execution. Three JS filters are CoreFilters: rewrite_javascript, combine_javascript, and inline_javascript.

Quick reference

Filter	Core	OFB	Description	Safe
rewrite_javascript	Yes	Yes	Minifies JS	Yes
rewrite_javascript_external	Yes	Yes	Implied by rewrite_javascript, external files only	Yes
rewrite_javascript_inline	Yes	Yes	Implied by rewrite_javascript, inline scripts only	Yes
combine_javascript	Yes	No	Combines multiple scripts	Yes
inline_javascript	Yes	No	Inlines small scripts	Yes
defer_javascript	No	No	Defers execution	Test first
outline_javascript	No	No	Externalizes large inline scripts	Experimental
include_js_source_maps	No	No	Preserves source maps	Yes

IIS syntax

On IIS, use the same filter names with the pagespeed prefix in pagespeed.config (no semicolons):

pagespeed EnableFilters rewrite_javascript,combine_javascript
pagespeed JsInlineMaxBytes 2048

See IIS Configuration for the full file format reference.

rewrite_javascript {#rewrite_javascript}

Core filter. Minifies JavaScript by removing whitespace, comments, and shortening variable names where safe. In OFB mode, minifies in-place. The sub-filters rewrite_javascript_external and rewrite_javascript_inline control scope but are implicitly enabled by the parent filter.

Apache:

ModPagespeedEnableFilters rewrite_javascript

Nginx:

pagespeed EnableFilters rewrite_javascript;

combine_javascript {#combine_javascript}

Core filter. Combines multiple <script src> elements into a single file. Like combine_css, combination boundaries are broken by inline scripts or other non-script elements between script tags.

Apache:

ModPagespeedEnableFilters combine_javascript

Nginx:

pagespeed EnableFilters combine_javascript;

inline_javascript {#inline_javascript}

Core filter. Inlines small external JS files into the HTML. JsInlineMaxBytes (default: 2048) controls the threshold.

Apache:

ModPagespeedEnableFilters inline_javascript
ModPagespeedJsInlineMaxBytes 2048

Nginx:

pagespeed EnableFilters inline_javascript;
pagespeed JsInlineMaxBytes 2048;

defer_javascript {#defer_javascript}

Not a core filter. Test thoroughly before enabling. Defers execution of all JavaScript until after the page finishes loading. This can dramatically improve initial render time but will break scripts that rely on executing during page parse (e.g., document.write).

Apache:

ModPagespeedEnableFilters defer_javascript

Nginx:

pagespeed EnableFilters defer_javascript;

Risks

• Scripts using document.write will fail.
• Scripts that expect to run before DOMContentLoaded may break.
• Order-dependent scripts may execute in unexpected order.
• Inserts a <noscript> redirect by default. Disable with SupportNoScriptEnabled false.

outline_javascript {#outline_javascript}

Experimental. Externalizes large inline <script> blocks into separate files. JsOutlineMinBytes (default: 3000) controls the threshold. Rarely useful — most sites benefit more from inlining.

Apache:

ModPagespeedEnableFilters outline_javascript
ModPagespeedJsOutlineMinBytes 3000

Nginx:

pagespeed EnableFilters outline_javascript;
pagespeed JsOutlineMinBytes 3000;

include_js_source_maps {#include_js_source_maps}

Not a core filter. Preserves JavaScript source maps through minification by adding a //# sourceMappingURL= comment pointing to the original source map. Enable this if you need to debug minified JavaScript in production.

Apache:

ModPagespeedEnableFilters include_js_source_maps

Nginx:

pagespeed EnableFilters include_js_source_maps;

Tuning parameters

Parameter	Default	Description
JsInlineMaxBytes	2048	Max JS file size (bytes) to inline
JsOutlineMinBytes	3000	Min inline JS size (bytes) to externalize

Apache:

ModPagespeedJsInlineMaxBytes 2048
ModPagespeedJsOutlineMinBytes 3000

Nginx:

pagespeed JsInlineMaxBytes 2048;
pagespeed JsOutlineMinBytes 3000;

See also

• Filter Selection
• Filter Reference