Fixing Render-Blocking JavaScript

What makes a script block rendering

The HTML parser reads your page from top to bottom. When it meets a classic script tag with a src and no async, defer or type="module", it has to assume the script might change what comes next, for example by writing into the page. So it pauses: nothing below the tag is parsed until the file has downloaded and run. When that tag is in the head, nothing in the body exists yet, so there is nothing to paint.

Three details make this worse than it sounds:

• Blocking scripts queue behind stylesheets. A classic script will not run until every stylesheet above it has loaded, because the script might ask for computed styles. A slow stylesheet therefore delays the script, and the script delays everything after it.
• Each one adds a round trip. Browsers scan ahead and start downloading later files early, which helps, but every blocking file still has to arrive and execute in order before parsing resumes.
• Other domains cost more. A script on a domain the page has not contacted yet needs a DNS lookup and a secure connection before its first byte.

Inline scripts, written directly in the page, do not need a download, but they still stop the parser while they run, and they still wait for stylesheets above them. A long inline script in the head blocks just like an external one.

defer, async and module: what each one changes

Some rules that trip people up:

• defer and async only work on scripts with a src. On a classic inline script they are ignored and the code runs straight away. Inline module scripts are the exception: they are deferred automatically.
• If a tag has both async and defer, browsers that understand async use it. There is no reason to write both today.
• Deferred scripts all run before the DOMContentLoaded event fires, so code waiting for that event can safely use anything a deferred script defines.
• Moving a script to the end of the body helps the content above it appear, but the parser still stops there. Adding defer in the head is usually better, because the download starts earlier.

How to find the blocking scripts

The JavaScript Checker flags render-blocking scripts on each page you test and lists every script with its size and parse and execution time, so you can see which blockers are also expensive to run. PageSpeed Insights reports the same problem in its render-blocking requests insight, listing stylesheets and scripts together with an estimate of the delay; read the file names to separate the two.

In Chrome, you can ask the browser directly which script files it treated as blocking on the load you just made:

performance.getEntriesByType('resource')
  .filter((r) => r.initiatorType === 'script' && r.renderBlockingStatus === 'blocking')
  .forEach((r) => console.log(r.name, Math.round(r.responseEnd - r.startTime), 'ms'));

Then view the page source, not the Elements panel, and search for <script in the head. For every tag, note whether it has a src, whether it has defer, async or a module type, and whether any inline code below it depends on it. That list is your working plan. On CMS sites, check several templates: home, category, product and blog posts often load different plugin scripts.

The fix, step by step

Before and after: a typical theme head

This head, based on a common older theme pattern, blocks the first paint three times: once for the library, once for the slider plugin and once for the inline code.

<!-- Before -->
<head>
  <link rel="stylesheet" href="/css/site.css">
  <script src="/js/jquery.min.js"></script>
  <script src="/js/slider.min.js"></script>
  <script>
    $(function () { $('.hero-slider').slider({ speed: 400 }); });
  </script>
  <script src="https://widgets.example.net/reviews.js"></script>
</head>

<!-- After -->
<head>
  <link rel="stylesheet" href="/css/site.css">
  <script src="/js/jquery.min.js" defer></script>
  <script src="/js/slider.min.js" defer></script>
  <script src="/js/home.js" defer></script>
  <script src="https://widgets.example.net/reviews.js" async></script>
</head>

// /js/home.js - runs after jQuery and the slider, in order
$('.hero-slider').slider({ speed: 400 });

The inline code moved into a small deferred file listed after the libraries it needs. The reviews widget depends on nothing and nothing depends on it, so it became async. If you cannot move inline code into a file, for example because a CMS prints it, wrap it instead:

document.addEventListener('DOMContentLoaded', function () {
  $('.hero-slider').slider({ speed: 400 });
});

Snippets that deliberately hold the page back

A few kinds of script are designed to run before the page shows. Each is worth questioning.

A/B testing and personalisation

Client-side testing tools change the page after it loads, so they often ship an anti-flicker snippet that hides the whole page until the testing script has run or a timeout expires. That can add seconds of blank screen for every visitor, including those not in any test. Options, from best to least effective: run tests on the server or at the CDN edge instead; load the snippet only on pages with a live test; or cut the timeout to the shortest value the vendor supports. Remove the snippet completely when a testing tool is retired; old anti-flicker code for discontinued tools is still found on many sites.

Consent tools

Consent management platforms usually ask to be placed first in the head. If you use Google consent mode, the small inline block that sets the default consent state does need to run before tags load, and it is tiny. The banner script itself rarely needs to block; check whether your provider offers an asynchronous loading option and test that tags still respect the stored choice when you use it. This is not legal advice; check your consent set-up with whoever is responsible for compliance before changing the order.

document.write

Older advertising and widget snippets use document.write to insert further scripts. Those inserted scripts block the parser, and Chrome may refuse to load cross-origin scripts inserted this way for users on slow connections, so the snippet can both slow the page and fail. Browsers also ignore document.write called from a deferred or async script. Ask the vendor for their current loader.

Platform notes

WordPress

Since WordPress 6.3, themes and plugins can ask for a loading strategy when they register a script, by passing an array such as array( 'strategy' => 'defer', 'in_footer' => false ) as the last argument of wp_register_script or wp_enqueue_script. WordPress then works out a safe strategy based on dependencies, falling back to blocking if a dependant needs it. Themes and plugins that do not use this still print blocking tags; performance plugins can add defer for you, but exclude jQuery and anything that inline code calls if pages break, and test page builders carefully.

Shopify

The script_tag Liquid filter outputs a plain blocking tag. In theme.liquid and section files, write the tag yourself with the asset_url filter for the address and add defer. Scripts from apps arrive through app embeds and content_for_header; you cannot edit those tags directly, so switch off app embeds you do not use and raise blocking scripts with the app developer.

Frameworks and static sites

Bundlers such as Vite output module scripts, which are deferred by default, so the main bundle rarely blocks. Blocking tags usually come from third-party snippets pasted into the base template. In Next.js, load those through next/script with the afterInteractive or lazyOnload strategy rather than a raw tag in the document head.

Edge cases

• A flash of the wrong theme or layout. Some small scripts exist to set a class before paint, for a dark mode preference or a no-JavaScript fallback. Keep these inline and tiny rather than deferring them.
• Scripts inside the body. A blocking tag halfway down the body lets the content above it render, but stops everything below, including images further down. Treat it like one in the head.
• The blocking attribute. Chromium supports a blocking="render" attribute that makes a script deliberately render-blocking. If you find it in a template, check that someone meant it.
• Deferring does not make code faster. Once a deferred script runs, it takes as long as it always did. If the page appears quickly but stays unresponsive, the problem has moved to long tasks, not been solved.