Exclude JavaScript files from Jetpack Boost deferral

This article explains how to stop Jetpack Boost from deferring specific JavaScript files or entire pages. You can exclude individual scripts by handle, add the data-jetpack-boost="ignore" attribute to a script tag, or skip JS deferral on whole pages that match a URL pattern. Use these exclusions when deferring JavaScript causes layout problems or breaks page functionality.

When to exclude JavaScript from deferral

If you experience unwanted website behavior when you defer JavaScript (JS) with Jetpack Boost, the affected functionality could rely on the JavaScript files being in a certain order or being made available to the page as soon as possible.

Jetpack Boost gives you two ways to handle this. You can exclude individual scripts so the rest of the page still benefits from deferral, or you can exclude an entire page when deferral causes problems across the whole page.

• Script-level exclusions stop Jetpack Boost from deferring a specific script while still deferring the other scripts on the page. Use this method when one script needs to load immediately or in a fixed order.
• Page-level exclusions stop Jetpack Boost from deferring any JavaScript on pages that match a URL pattern. Use this method when deferral causes layout or JavaScript execution issues across an entire page, such as a checkout page or a gallery page.

Exclude an individual script from deferral

You can tell Jetpack Boost not to defer a specific file by adding the attribute data-jetpack-boost="ignore" to the script tag. The method you use depends on whether the script tag is hardcoded or enqueued with wp_enqueue_script.

If your script tag is hardcoded, add the attribute directly to the tag:

<script data-jetpack-boost="ignore">

Exclude a script enqueued with wp_enqueue_script

If your script tag is enqueued with wp_enqueue_script like the following:

function wpdemo_enqueue_scripts() {
    wp_enqueue_script( 'wpdemo', get_template_directory_uri().'/js/wpdemo.js' );
}
add_action( 'wp_enqueue_scripts', 'wpdemo_enqueue_scripts' );

You can use the example snippet below and add it to your theme’s functions.php file:

function add_data_jetpack_boost_tag( $src, $handle ) {
    if ( $handle !== 'wpdemo') {
        return $src;
    }
    return str_replace( ' src', ' data-jetpack-boost="ignore" src', $src );
}
add_filter( 'script_loader_tag', 'add_data_jetpack_boost_tag', 10, 2 );

Remember to replace wpdemo with the handle of the script file you want to exclude.

Exclude an entire page from deferral

Starting in Jetpack Boost 4.6.2, the Defer Non-Essential JavaScript feature includes a per-page URL pattern exclusion list. This list stops Jetpack Boost from deferring any JavaScript on pages whose URL matches a pattern you enter, without disabling the Defer JS feature across your whole site.

To add a page-level exclusion, follow these steps:

1. Go to Jetpack → Settings and open the Jetpack Boost settings panel.
2. Find the Defer Non-Essential JavaScript feature.
3. Enter one or more URL patterns in the exclusion list. The panel shows an inline example of the expected format.
4. Save your changes.

URL pattern syntax

The URL pattern syntax for page-level exclusions matches the syntax used for Page Cache exclusions. You can enter a plain text fragment such as checkout, or a pattern with a wildcard such as gallery/(.*). Any page whose URL matches a pattern in the list is excluded from JS deferral.

For more detail on how the pattern matching works, see Excluding specific parts of the site from caching.