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.
In this Article
- First steps
- Issues
- Techniques to solve issues
- Use the One-click exclusions
- Use the Excluded JavaScript Files text area
- General dependencies exclusions
- Check the console
- Check by context
- Process of elimination
- Exclusions
- Default exclusions
- Patterns of exclusions
- External scripts exclusions
- Paired exclusions
- Page-specific exclusions
- Exclusions by attribute
- Examples
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 aPREG_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 thepcre.backtrack_limit
, by addingiini_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.
- Go to the URL where you see the issue. E.g. https://example.com/.
- 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 areUncaught ReferenceError: example_code is not defined
andUncaught ReferenceError: example_code is not a function
Above's error means theexample_code
function or variable was required, but it wasn't available, in this case, due to its definition being delayed. - 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. - 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:
- Put
example_code
into the Search bar, this will list all the scripts using and definingexample_code
. - 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:
- Go to the URL where you see the issue. E.g. https://example.com/.
- Identify the affected element. E.g. the mobile hamburger menu.
- 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.
- Identify the class related to the element, as shown in the image below:
- 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. - Use the Search tab to find the linked scripts.
- 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:
- Go to the URL where the issue appears.
- Open the console and look for any JavaScript errors:
In this case,woof_current_values
andwoof_autosubmit
are the affected functions. - Open another tab and go to the same URL with
?nowprocket
. - Open the console in this tab, too, and open the Search tab.
- 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. - Put all the listed files into the Delay JavaScript execution's exclusion box.
Save changes and check if the issue is gone.
- The filter issue is still happening, and a new error appeared in the console, see:
-
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.
-
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. -
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:
- Go to the URL where the issue appears.
- Identify the mobile hamburger menu element, which is located at the top right of the page.
- Find the hamburger menu markup in the HTML with Inspect element.
- Identify the class related to the hamburger menu. In this case, the class is
burger
as shown below: - Open another tab and go to the same URL with the ?nowprocket string.
- Use the Search tab to find the scripts linked to the
burger
class, as shown below:
- 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.