How to Defer and Delay JavaScript with LiteSpeed Cache: A Complete Guide

The Core Challenge: Mixing Defer and Delay

Many users want to defer most scripts for general performance but delay specific, non-critical scripts (like certain analytics or cookie consent tools) until user interaction. The threads show this is a frequent point of confusion.

The LiteSpeed Cache plugin handles this through a specific configuration:

1. Set the main Load JS Deferred option to Deferred (not Delayed).
2. Navigate to Tuning -> JS Delay Includes.
3. Add the specific script identifiers (URLs or unique strings) you want to delay.

This approach allows you to maintain deferred loading for most scripts while selectively delaying others. However, as noted in the threads, there are some important limitations and considerations.

Common Issues and Solutions

1. Scripts with Existing Defer Attributes Won't Delay

If a script already has a defer attribute in its code, the LiteSpeed Cache optimization logic will exclude it from being delayed, even if you add it to the Delay Includes list. This is by design in the plugin's codebase to prevent conflicts.

2. Handling Inline JavaScript

To exclude a chunk of inline JavaScript from being deferred, you can add any unique string from that code to your exclusion lists. The more unique the string (like a specific function name func1), the less likely it is to cause unintended exclusions elsewhere.

3. Applying Different Settings to Specific Pages

You might want to delay JavaScript on most pages but use a different method on your homepage. This can be achieved with a code snippet added to your theme's functions.php file:

add_action( 'litespeed_optm', function() {
    if (is_front_page()) {
        do_action( 'litespeed_conf_force', 'optm-js_defer', 2 );
    }
} );

This code forces the homepage to use delayed JS (value 2) while other pages follow your general deferred setting.

4. Debugging When Settings Don't Work

If your defer/delay configurations aren't working as expected, enable debugging:

1. Go to Toolbox -> Debug Settings
2. Set Debug Log to ON
3. Set Debug Level to Advanced
4. Add your URI to Debug Includes URI
5. Check the Toolbox -> Log View for detailed information

Advanced Technique: Adding Defer to Specific Scripts

In some cases, you might need to add a defer attribute to a specific script that isn't being handled by your general settings. For instance, to defer the Instant Click script while keeping other settings intact, you could use:

function add_defer_to_instant_click($tag, $handle) {
    if ('litespeed-cache' === $handle && strpos($tag, 'instant_click') !== false) {
        return str_replace(' src', ' defer src', $tag);
    }
    return $tag;
}
add_filter('script_loader_tag', 'add_defer_to_instant_click', 10, 2);

Key Takeaways

• Use Deferred as your main setting and selectively add scripts to JS Delay Includes for a mixed approach
• Scripts with existing defer attributes cannot be delayed through the plugin interface
• Use unique strings from inline scripts to exclude them from optimization
• Enable debug logging when configurations don't work as expected
• Consider code snippets for page-specific JavaScript loading behavior

Properly configuring JavaScript deferral and delaying can significantly improve your site's performance metrics. Start with conservative settings, test thoroughly, and use the debugging tools to identify and resolve any issues that arise.