Initial commit

2026-04-17 07:21:17 +00:00
commit fe38508201
470 changed files with 74105 additions and 0 deletions
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## 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):**
+
+```tsx
+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):**
+
+```tsx
+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:
+
+```tsx
+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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)