Skip to content

ever-co/ever-works / .agents/skills/next-best-practices

next-best-practices

Verified

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

FileKindSize
SKILL.mdskill md3.9 KB
async-patterns.mdmarkdown1.6 KB
bundling.mdmarkdown4.6 KB
data-patterns.mdmarkdown6.6 KB
debug-tricks.mdmarkdown2.9 KB
directives.mdmarkdown1.4 KB
error-handling.mdmarkdown4.6 KB
file-conventions.mdmarkdown3.7 KB
font.mdmarkdown5.0 KB
functions.mdmarkdown5.8 KB
hydration-error.mdmarkdown1.7 KB
image.mdmarkdown3.8 KB
metadata.mdmarkdown7.1 KB
parallel-routes.mdmarkdown7.1 KB
route-handlers.mdmarkdown3.3 KB
rsc-boundaries.mdmarkdown4.6 KB
runtime-selection.mdmarkdown986 B
scripts.mdmarkdown3.6 KB
self-hosting.mdmarkdown8.5 KB
suspense-boundaries.mdmarkdown1.4 KB

scripts.md

View on GitHub
# Scripts

Loading third-party scripts in Next.js.

## Use next/script

Always use `next/script` instead of native `<script>` tags for better performance.

```tsx
// Bad: Native script tag
<script src="https://example.com/script.js"></script>;

// Good: Next.js Script component
import Script from 'next/script';

<Script src="https://example.com/script.js" />;
```

## Inline Scripts Need ID

Inline scripts require an `id` attribute for Next.js to track them.

```tsx
// Bad: Missing id
<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />

// Good: Has id
<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />

// Good: Inline with id
<Script id="show-banner">
  {`document.getElementById('banner').classList.remove('hidden')`}
</Script>
```

## Don't Put Script in Head

`next/script` should not be placed inside `next/head`. It handles its own positioning.

```tsx
// Bad: Script inside Head
import Head from 'next/head'
import Script from 'next/script'

<Head>
  <Script src="/analytics.js" />
</Head>

// Good: Script outside Head
<Head>
  <title>Page</title>
</Head>
<Script src="/analytics.js" />
```

## Loading Strategies

```tsx
// afterInteractive (default) - Load after page is interactive
<Script src="/analytics.js" strategy="afterInteractive" />

// lazyOnload - Load during idle time
<Script src="/widget.js" strategy="lazyOnload" />

// beforeInteractive - Load before page is interactive (use sparingly)
// Only works in app/layout.tsx or pages/_document.js
<Script src="/critical.js" strategy="beforeInteractive" />

// worker - Load in web worker (experimental)
<Script src="/heavy.js" strategy="worker" />
```

## Google Analytics

Use `@next/third-parties` instead of inline GA scripts.

```tsx
// Bad: Inline GA script
<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
<Script id="ga-init">
  {`window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'G-XXXXX');`}
</Script>

// Good: Next.js component
import { GoogleAnalytics } from '@next/third-parties/google'

export default function Layout({ children }) {
  return (
    <html>
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XXXXX" />
    </html>
  )
}
```

## Google Tag Manager

```tsx
import { GoogleTagManager } from '@next/third-parties/google';

export default function Layout({ children }) {
	return (
		<html>
			<GoogleTagManager gtmId="GTM-XXXXX" />
			<body>{children}</body>
		</html>
	);
}
```

## Other Third-Party Scripts

```tsx
// YouTube embed
import { YouTubeEmbed } from '@next/third-parties/google';

<YouTubeEmbed videoid="dQw4w9WgXcQ" />;

// Google Maps
import { GoogleMapsEmbed } from '@next/third-parties/google';

<GoogleMapsEmbed apiKey="YOUR_API_KEY" mode="place" q="Brooklyn+Bridge,New+York,NY" />;
```

## Quick Reference

| Pattern                                       | Issue                      | Fix                       |
| --------------------------------------------- | -------------------------- | ------------------------- |
| `<script src="...">`                          | No optimization            | Use `next/script`         |
| `<Script>` without id                         | Can't track inline scripts | Add `id` attribute        |
| `<Script>` inside `<Head>`                    | Wrong placement            | Move outside Head         |
| Inline GA/GTM scripts                         | No optimization            | Use `@next/third-parties` |
| `strategy="beforeInteractive"` outside layout | Won't work                 | Only use in root layout   |
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall