Troubleshoot Delay JavaScript execution issues

In this article, you'll learn how to identify, differentiate and solve issues related to the Delay JavaScript execution feature, how to handle exclusions and some examples.

Heads up! This is an advanced-level document dedicated to experienced users or developers.

If you need further assistance or simply prefer, you can contact WP Rocket's support instead.

First steps

Start by making sure Delay JavaScript execution is the problematic feature.

In order to do this, the issue should happen only under the following circumstances:

• Delay JavaScript execution is enabled.
• All the other features in the File Optimization tab are disabled.

Then, you should disable Delay JavaScript execution and the issue should be gone. If that's so, then you've made sure Delay JavaScript execution is the problematic feature.

Note: It's recommended to fix any pre-existent errors in Developer Tools > Console, as they might interfere with the functionality of the site and, for this matter, with the troubleshooting process.

Once you've confirmed Delay JavaScript execution is causing the issue, you should identify if the issue is esthetic-only or if it's affecting the actual website functionality.

Issues

There can be esthetic, layout or functionality, and common issues related to Delay JavaScript execution.

Esthetic-only issues

When using Delay JavaScript execution, certain elements can appear only after some time or user's interaction. If this doesn't interfere with the website's regular functioning, this could be considered an esthetic-only issue.

For this type of issue, you can choose between prioritizing user experience or performance, as follows:

• User experience: your website visitors will have the best UI experience.
  
  In order to provide your visitors with the best usability, you should find and exclude the affected script(s) from Delay JavaScript execution, as explained further in this article. Excluding files will result in a degraded performance.
• Performance: your website visitors will have the best possible speed.
  
  To provide your visitors with the biggest possible optimization, you should not exclude the affected file(s) from Delay JavaScript execution. Visitors will have to wait some time or perform an interaction before being able to interact or see the specific elements, with a slightly degraded user experience.

Layout or functionality issues

If an element isn't working properly even after some time, or after user interaction, then it should be considered a layout or functionality issue. In this case, you should exclude the affected file(s) to provide your visitors with the proper website usability.

Common Issues

These are the common issues you should have in mind:

• Lazyload for Images:
  
  Some themes provide their own version of the lazyload feature for images. Or you may be using a 3rd-party plugin to apply lazyload.
  
  When the Delay JavaScript Execution feature is enabled, images may not be displayed at all or may require a user to interact with the page for them to become visible.
  
  In such cases, we recommend disabling the theme or plugin lazyload feature and use WP Rocket's LazyLoad instead.
  We automatically exclude Smush and EWWW's lazyload features. If you are using either of these plugins, you don't need to disable their lazyload.
• Preloaders:
  
  Preloaders are a feature some themes/plugins offer to hide the content of a page until that's fully rendered - usually, a spinner/loader icon is displayed.
  
  With Delay JavaScript Execution, the loader will continue to spin up until a user interacts with the page. To be able to delay all files, you'll need to disable the preloader option in your theme.
  
  This is also better for the user experience since visitors will be able to see a page's content earlier.
• Delay JavaScript execution not working in specifics pages:
  
  In rare ocasions, parsing specific HTML code can trigger a PREG_BACKTRACK_LIMIT_ERROR PHP error. When that kind of error takes place, WP Rocket doesn't apply Delay JavaScript Execution to that page.
  
  As a workaround, you can try increasing the pcre.backtrack_limit, by adding ini_set('pcre.backtrack_limit', 99999999); to your wp-config.php file, or ask your hosting provider to increase it for you.
• Links needs to be clicked twice on iOS / Safari:
  
  On Safari browser in iOS, when Delay JavaScript execution is enabled, links have to be clicked twice for them to work.
  
  The currently recommended option is to disable Delay JavaScript execution feature.
  
  However, if you're comfortable with code, you can also try editing the delay script as per this or this other workaround. Please note, these edits will be removed everytime WP Rocket is updated.
• New Relic Real User Monitoring:
  
  The JavaScript added by this service can interfere with the Delay JavaScript Execution feature, preventing some site elements from working unless all scripts are excluded.
  
  There is no solution besides disabling New Relic.
  
  To check if New Relic is active on your site, look for the following code  in your page source:
  <script type="text/javascript">(window.NREUM||(NREUM={}))

Techniques to solve issues

The following are the most useful techniques to find the right files to exclude from Delay JavaScript execution.

Note: Some issues might require you to use the same technique a couple of times, or to combine techniques.

Use the One-click exclusions

You can click on the plugin/theme/service-specific boxes in the One-click exclusions section under the Delay JavaScript execution feature:

Use the Excluded JavaScript Files text area

If you're using an old WP Rocket version, or if your plugin/theme/service-specific exclusions are not found in the One-click exclusions section, you can manually add your custom scripts into the Excluded JavaScript Files text area, like this: 

General dependencies exclusions

You can refer to the exclusions in this article, in case your site has JavaScript errors for general dependencies:

General dependencies exclusions

Check the console

Using the console will show you if there is any JavaScript error that will lead you to identify the affected file and then, the right file to exclude.

1. Go to the URL where you see the issue. E.g. https://example.com/.
2. Open the console, in Developer Tools and look for any JavaScript errors. These errors mention the scripts that are having issues and will lead you to the right file to exclude. You check this article for more information.
   
   The most common errors to find are Uncaught ReferenceError: example_code is not defined and Uncaught ReferenceError: example_code is not a function
   
   Above's error means the example_code function or variable was required, but it wasn't available, in this case, due to its definition being delayed.
3. Open another tab and go to the same URL with ?nowprocket attached to the end, to bypass WP Rocket's optimizations. E.g. https://example.com/?nowprocket.
4. Open the console in this tab, too, and open the Search tab, which lets you search for text across all loaded resources. In Chrome, you can click on the three dots at the right, as shown in below's picture:
   

   

5. Put example_code into the Search bar, this will list all the scripts using and defining example_code.
6. Put all the listed files into the Delay JavaScript execution's exclusion box, save changes and check if the issue is gone.

In an additional step, you can remove the excluded files, one by one, checking the error does not come back, in order to further refine the exclusions.

Sometimes, there are other files that are dependent on the exclusions and new console errors can appear. In these cases, you need to use the console technique again.

Check by context

You can also find exclusions by focusing on the context.

The idea with this technique, is to explore and finding any scripts related to the affected feature, and find the required exclusions faster.

You may get a clue by searching for the class that's added in the element. Usually, JavaScript will use that class to work as expected.

The following would be the steps to apply the context technique:

1. Go to the URL where you see the issue. E.g. https://example.com/.
2. Identify the affected element. E.g. the mobile hamburger menu.
3. Find the element's markup in the HTML with one of these two options:
• Right-click on the element to open the contextual menu and click on Inspect element.
• Open the Elements tab in Developer Tools.
4. Identify the class related to the element, as shown in the image below:
   

   

5. Open another tab and go to the same URL. Bypass WP Rocket's optimizations with ?nowprocket attached to the end. E.g. https://example.com/?nowprocket.
6. Use the Search tab to find the linked scripts.
7. Add all the listed scripts into the Delay JavaScript execution's exclusion box, save changes and check if the issue is gone.

You can refine the findings by removing the excluded files, one by one, checking the issue behavior each time.

Process of elimination

You can also find the right exclusions by following a process of elimination, as described in the following article:

Resolving Issues with Minify CSS & Combine CSS

Above's tutorial mentions CSS but it can be applied to JavaScript as well.

Exclusions

There are different ways to handle Delay JavaScript execution exclusions according to their nature.

Default exclusions

To quickly resolve issues, you can remove any existing exclusions, add the following default exclusions, and check if the issue is resolved:

\/jquery(-migrate)?-?([0-9.]+)?(.min|.slim|.slim.min)?.js(\?(.*))?( |'|"|>)
js-(before|after)
(?:/wp-content/|/wp-includes/)(.*)

The above's lines will exclude all scripts in the /wp-content and /wp-includes folders, jQuery file and it's filename variations, and inline scripts that are added by themes/plugins using the wp_add_inline_script() WordPress function.

In other words, the majority of your website's scripts won't be delayed and, in this sense, the issues should be gone.

This also means that your website won't have most of the Delay JavaScript execution's expected performance improvement.

Therefore, you should always refine the exclusions with the techniques described above, or with the help of the support team.

Note: Using default exclusions is not recommended. This should be a last resource, in cases where finding exclusions gets too complex.

Patterns of exclusions

The following are the main patterns you can use to handle exclusions:

/plugins/(.*)
/themes/(.*)
/wp-includes/(.*)
/uploads/(.*)
/cache/min/(.*)
\(
\{

/plugins/(.*), /themes/(.*), /wp-includes/(.*), /uploads/(.*) and /cache/min/(.*) will exclude all the scripts in the respective folders.

\( and \{ will exclude all the inline scripts.

Heads up!

Certain patterns of exclusions cannot be handled and are automatically removed.

If you add them, you should see a notice with the "WP Rocket: The following patterns are invalid and have been removed" message.

Please see more in our Invalid patterns of exclusions article.

External scripts exclusions

To exclude an external script, you should use the script's filename, and sometimes, a part of the path. Avoid using the external domain of an external script.

This is because when Minify JavaScript files is enabled, the script will be hosted locally, in your server. In this case, the domain in the exclusions list won't be a match and the script won't be excluded.

Example: To exclude the ads.com/ads-folder/script.js file, you should put /ads-folder/script.js in the exclusions box.

Paired exclusions

The jQuery and jQuery Migrate files should be excluded together with the following line:

\/jquery(-migrate)?-?([0-9.]+)?(.min|.slim|.slim.min)?.js(\?(.*))?( |'|"|>)

Page-specific exclusions

It can be useful to exclude scripts from Delay JavaScript execution but only in some affected URLs instead of excluding them globally.

For this, please use the helper plugin as described in the following guide:

Exclude JS scripts from Delay JavaScript Execution only at some URLs

Exclusions by attribute

The keyword  "nowprocket" is designed to trigger exclusion when used as part of a file name, attribute name or value, or within script content (such as in a comment).

Programmatically, exclusion can be achieved by adding for instance  data-nowprocket attribute.

The following example script tags will be excluded from being delayed:

script data-nowprocket src='https://yourdomain.com/wp-content/themes/script.js'></script>

<script data-nowprocket>
	function myFunction() {
		// Some code
	}
</script>

<script>
    // nowprocket
	function myFunction() {
		// Some code
	}
<script>

Examples

Check the console example

The following is an example of how to apply the console technique, in an issue with the WOOF - Products Filter for WooCommere (WOOF) plugin.

In this case, visitors can't filter the products search results, thus, Delay JavaScript execution is affecting WOOF's actual functionality, and you need to find an exclusion.

After completing the first steps, these are the steps to use the console technique:

1. Go to the URL where the issue appears.
2. Open the console and look for any JavaScript errors:
   

   
   In this case, woof_current_values and woof_autosubmit are the affected functions.

3. Open another tab and go to the same URL with ?nowprocket.
4. Open the console in this tab, too, and open the Search tab.
5. Put woof_current_values into the Search bar, this will list all the scripts using and defining this function. In this case, you can see the listed files as shown below:
   
   

   

   The same list is presented when searching for the woof_autosubmit function.

6. Put all the listed files into the Delay JavaScript execution's exclusion box.
   
   

   

   Save changes and check if the issue is gone.

7. The filter issue is still happening, and a new error appeared in the console, see:
   

   

8. Follow a similar procedure to what was done above but for the jQuery function.
   
   Have in mind the jQuery file is linked to a paired exclusion with the jQuery Migrate file.
   
   Or, simply, use the jQuery not defined guide here.
   

9. Since there are many WOOF's files to exclude, you should merge them to avoid any possible new errors with other WOOF files. Use the following wildcard:
   
   /woocommerce-products-filter/(.*)
   
   This will exclude all JavaScript from the /woocommerce-products-filter/ folder.

10. These are the final exclusions:

    /jquery-?[0-9.](.*)(.min|.slim|.slim.min)?.js
    /jquery-migrate(.min)?.js
    /woocommerce-products-filter/(.*)
    	

Check by context example

In this example, Delay JavaScript execution prevents the hamburger mobile menu from being clicked.

In order to find the exclusions you should follow these steps:

1. Go to the URL where the issue appears.
2. Identify the mobile hamburger menu element, which is located at the top right of the page.
3. Find the hamburger menu markup in the HTML with Inspect element.
4. Identify the class related to the hamburger menu. In this case, the class is burger as shown below:

   

5. Open another tab and go to the same URL with the ?nowprocket string.
6. Use the Search tab to find the scripts linked to the burger class, as shown below:
   

   

7. Add the /themes/V4/assets/js/scripts.min.js script to the Delay JavaScript execution's exclusion box, save changes and check if the issue is gone.

Basic examples

Excluding a file

/wp-content/plugins/gravityforms/js/gravityforms.min.js?ver=2.4.23

To specify only this file, the following will work:

gravityforms/js/gravityforms.min.js

Removing the version number is recommended so that the file will still be excluded if it changes.

Excluding multiple files

Excluding multiple files can be done in one of two ways. To exclude all files under /gravityforms/js/, use either of the following:

1. The exclusion method detects keywords, not just filepaths, so the simplest method is to use:

/wp-content/plugins/gravityforms/js/

2. Wildcards can also be used:

/wp-content/plugins/gravityforms/js/(.*).js

Excluding an inline script

To exclude an inline script, choose a string of text that is unique to that script.

 <script type="text/javascript">
        (function () {
            var c = document.body.className;
            c = c.replace(/woocommerce-no-js/, 'woocommerce-js');
            document.body.className = c;
        })()
    </script>

In this example, /woocommerce-no-js/ is a good choice, since it should be specific to this script.

Edge Issues

Errors Related to Content Security Policy Restrictions
If your site uses a restrictive Content Security Policy (CSP), delayed scripts may fail to load, resulting in a console error similar to this:

example-page/:3 Refused to load the script 'data:text/javascript;base64,CiAgd2luZG93LmRhdGFMYXllciA9IHdpbmlnJywgJ0ctQkRGSDg3R0w0UycpOwo=' because it violates the following Content Security Policy directive: "default-src https: blob: 'unsafe-inline' 'unsafe-eval'". Note that 'script-src-elem' was not explicitly set, so 'default-src' is used as a fallback.

The optimization converts some inline scripts to base64 encoded URIs that start with data:. Some CSP rules might block this, so you may need to apply something like the following in your CSP's script-src settings:

	Content-Security-Policy: script-src 'self' data: https://example.com;

This is aimed to permit scripts from your own domain, scripts using the data: protocol, and scripts served from any additional trusted domains. Contact your host for further assistance if the above doesn't resolve the error.