.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
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 orderasync: Downloads in parallel, executes immediately when ready, no guaranteed orderUse 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></body>
</html>
)
}
Correct (non-blocking):
export default function Document() {
return (
<html>
<head>
<script src="https://example.com/analytics.js" async />
<script src="/scripts/utils.js" defer />
</head>
<body></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