no-blocking-script

Why it matters

A <script src="..."> without defer, async, or type="module" blocks HTML parsing until the script downloads and executes. This delays the First Contentful Paint and Time to Interactive. Adding defer preserves execution order; async fires as soon as the script downloads; type="module" is always deferred.

See the difference

---
---
<html lang="en">
  <head>
    <script src="/analytics.js"></script>
  </head>
</html>

---
---
<html lang="en">
  <head>
    <!-- defer — preserves execution order, non-blocking -->
    <script src="/analytics.js" defer></script>
    <!-- async — fires as soon as downloaded, order not guaranteed -->
    <script src="/widget.js" async></script>
    <!-- type="module" is always deferred -->
    <script src="/app.js" type="module"></script>
  </head>
</html>

Configure this check

Override the default severity in your ESLint config:

import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'

export default [
  astroDoctorPlugin.configs.recommended,
  {
    rules: {
      'astro-doctor/no-blocking-script': 'error',
    },
  },
]

Or set the severity for CLI scans in doctor.config.ts:

export default {
  rules: {
    'astro-doctor/no-blocking-script': 'error',
  },
}

Use 'error', 'warn', or 'off'. The configuration guide covers presets and per-file overrides.

Keep exploring performance

• no-client-load-overusePrefer client:idle or client:visible over client:load for interactive islands.
• use-astro-imageUse <Image> from astro:assets instead of raw <img> tags.
• require-image-dimensionsRequire dimensions for public and remote astro:assets images.
• no-unprocessed-script-surprisesWarn when script attributes opt out of Astro script processing.

Browse every rule and project audit