Use defer or async on Script Tags

Impact: HIGH (eliminates render-blocking)

Script tags without defer or async block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.

defer: Downloads in parallel, executes after HTML parsing completes, maintains execution order
async: Downloads in parallel, executes immediately when ready, no guaranteed order

Use defer for scripts that depend on DOM or other scripts. Use async for independent scripts like analytics.

Incorrect (blocks rendering):

export default function Document() {
  return (
    <html>
      <head>
        <script src="https://example.com/analytics.js" />
        <script src="/scripts/utils.js" />
      </head>
      <body>{/* content */}</body>
    </html>
  )
}

Correct (non-blocking):

export default function Document() {
  return (
    <html>
      <head>
        {/* Independent script - use async */}
        <script src="https://example.com/analytics.js" async />
        {/* DOM-dependent script - use defer */}
        <script src="/scripts/utils.js" defer />
      </head>
      <body>{/* content */}</body>
    </html>
  )
}

Note: In Next.js, prefer the next/script component with strategy prop instead of raw script tags:

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
    </>
  )
}

Reference: MDN - Script element

Capability

Other metadata

metadata: { "priority": 4, "docs": [ "https://react.dev/reference/react", "https://react.dev/learn" ], "pathPatterns": [ "src/components/**/*.tsx", "src/components/**/*.jsx", "app/components/**/*.tsx", "app/components/**/*.jsx", "components/**/*.tsx", "components/**/*.jsx", "src/ui/**/*.tsx", "lib/components/**/*.tsx" ], "bashPatterns": [], "importPatterns": [ "react", "react-dom" ] }
validate: [ { "pattern": "from\\s+['\"](styled-components|@emotion/styled|@emotion/react|@mui/material|@chakra-ui/react)['\"]|styled\\.", "message": "Legacy CSS-in-JS or component library detected. Consider shadcn/ui + Tailwind for modern Vercel-native UI.", "severity": "warn", "upgradeToSkill": "shadcn", "upgradeWhy": "Migrate from CSS-in-JS/MUI/Chakra to shadcn/ui + Tailwind CSS for better SSR performance and Vercel ecosystem alignment.", "skipIfFileContains": "@/components/ui|shadcn|tailwindcss" } ]
retrieval: { "aliases": [ "react review", "component quality", "tsx linter", "react patterns" ], "intents": [ "review react code", "improve component quality", "check accessibility", "optimize react" ], "entities": [ "hooks", "accessibility", "React", "TSX", "component" ] }
chainTo: [ { "pattern": "from\\s+['\\\"](styled-components|@emotion/styled|@emotion/react|@mui/material|@chakra-ui/react)['\"]|styled\\.", "targetSkill": "shadcn", "message": "Legacy CSS-in-JS or component library detected — loading shadcn/ui guidance for modern Vercel-native UI." } ]

/react-best-practices

rulesrendering-script-defer-async.md

Use defer or async on Script Tags

Third-party checks

Provenance

Capability

/react-best-practices