# Defer JavaScript (defer_javascript)

Defers JS execution until after page load. The defer_javascript filter: what it does, its risks and the Apache, nginx and IIS directives.

Canonical URL: https://modpagespeed.com/docs/filters/defer_javascript/

- Category: JavaScript
- CoreFilters: No
- OptimizeForBandwidth: No
- Risk: Test first

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`).

## When to use it

- Not in CoreFilters: it runs only when you enable it by name.
- Risk rating on these docs: **Test first**.

## 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`.

- Since v1.15.0+r18, with `HonorCsp` (default on) the filter stands down entirely on pages whose `Content-Security-Policy` forbids inline scripts — deferral relies on injected inline JavaScript, which such a policy would block.

- Since v1.15.0+r21, `defer_javascript` — along with `disable_javascript`, `defer_iframe`, `fix_reflow`, and the shared `support_noscript` fallback — switches off for clients identified as automated, including clients that send no `User-Agent`; those clients receive the page's normal authored script markup. Search-engine crawlers are included deliberately. An automated client presenting a browser's exact user-agent string is indistinguishable from that browser and still receives the deferred form.

## Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

**Apache**

```apache
ModPagespeedEnableFilters defer_javascript
```

**nginx**

```nginx
pagespeed EnableFilters defer_javascript;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters defer_javascript
```

### On the worker

The worker runs its own pipeline, configured by flags. Its equivalent of this filter is the [script deferral](https://modpagespeed.com/docs/worker-configuration/#script-deferral) transform. Runs as part of HTML optimization when [browser analysis](https://modpagespeed.com/docs/worker-configuration/#browser-analysis) has produced a script profile; it has no flag of its own.

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Live example

See the before and after, with the source diff: [defer_javascript example](https://modpagespeed.com/examples/defer_javascript/).

## Frequently asked questions

**What does the defer_javascript filter do?**

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`).

**Is defer_javascript enabled by default?**

No. `defer_javascript` is not in CoreFilters, the default RewriteLevel; it runs only when you enable it by name with `EnableFilters`.

**How do I enable defer_javascript on Apache and nginx?**

Add `ModPagespeedEnableFilters defer_javascript` on Apache or `pagespeed EnableFilters defer_javascript;` on nginx. On IIS, add `pagespeed EnableFilters defer_javascript` to pagespeed.config.

## Related filters

- [`inline_javascript`](https://modpagespeed.com/docs/filters/inline_javascript/): Inline JavaScript
- [`combine_javascript`](https://modpagespeed.com/docs/filters/combine_javascript/): Combine JavaScript
- [`lazyload_images`](https://modpagespeed.com/docs/filters/lazyload_images/): Lazy-load images
- [`extend_cache_scripts`](https://modpagespeed.com/docs/filters/extend_cache_scripts/): Extend cache for scripts
- [`include_js_source_maps`](https://modpagespeed.com/docs/filters/include_js_source_maps/): Include JS source maps
- [`make_show_ads_async`](https://modpagespeed.com/docs/filters/make_show_ads_async/): Async AdSense
- [`outline_javascript`](https://modpagespeed.com/docs/filters/outline_javascript/): Outline JavaScript
- [`rewrite_javascript_external`](https://modpagespeed.com/docs/filters/rewrite_javascript_external/): Minify external JavaScript

This page is drawn from the [defer_javascript entry on JavaScript filters](https://modpagespeed.com/docs/javascript-filters/#defer_javascript). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).