Next.js + React Best Practices

Skill de performance para código React/Next.js, destilada das regras da engenharia da Vercel (70 regras em 8 categorias, priorizadas por impacto). Usada pelos implementers frontend e fullstack — dev-dev-alpha, dev-dev-gamma, sites-dev-alpha, sites-dev-beta, sites-dev-gamma — e pelos reviewers dev-qa / sites-qa em code review. Aplique na escrita de componentes novos, em refactors e em auditorias de bundle/render.

1. Eliminating Waterfalls (CRITICAL)

1.1 — Parallelize independent async operations with Promise.all().

// ❌ Sequential — 3 round trips
const user = await getUser(id)
const posts = await getPosts(id)
const stats = await getStats(id)

// ✅ Parallel — 1 round trip window
const [user, posts, stats] = await Promise.all([
  getUser(id), getPosts(id), getStats(id),
])

1.2 — Check cheap conditions before awaiting. Don't pay for a fetch you might discard.

// ❌ fetch always runs
const data = await fetchExpensive()
if (!flag.enabled) return null

// ✅ bail out first
if (!flag.enabled) return null
const data = await fetchExpensive()

1.3 — Move await into the branch that needs it. If only one code path consumes the promise, await it there — start the promise early, await late.

1.4 — Stream with Suspense instead of blocking the whole page. Fetch fast data in the page; wrap slow sections in <Suspense fallback={...}> and let them stream in.

export default async function Page() {
  const header = await getHeader() // fast
  return (
    <>
      <Header data={header} />
      <Suspense fallback={<Skeleton />}>
        <SlowSection /> {/* awaits inside, streams later */}
      </Suspense>
    </>
  )
}

1.5 — Pass promises down, await in the leaf. Start fetches high in the tree, pass the promise as prop, resolve with use() or await inside the Suspense boundary.

2. Bundle Size (CRITICAL)

2.1 — Import directly, never through barrel files.

// ❌ pulls the whole library through the barrel
import { Button } from '@/components'
// ✅ pulls one module
import { Button } from '@/components/button'

2.2 — next/dynamic for heavy, conditionally-shown components (charts, editors, modals, maps): const Chart = dynamic(() => import('./chart'), { ssr: false }).

2.3 — Load third-party scripts after hydration with next/script (strategy="lazyOnload" or afterInteractive). Never a raw <script> blocking render.

2.4 — Defer modules until the feature activates — dynamic import() inside the event handler that needs it (e.g., load the export-to-PDF lib on click).

2.5 — Keep client boundaries small. "use client" marks the top of a client subtree — everything it imports ships to the browser. Push "use client" down to the leaf interactive components; keep pages and layouts as Server Components.

3. Server-Side Performance (HIGH)

3.1 — Authenticate Server Actions like API routes. Every "use server" function is a public endpoint. Validate session + input inside the action, never only in the calling UI.

3.2 — React.cache() for per-request deduplication of repeated reads (e.g., getCurrentUser() called by layout + page + components).

export const getCurrentUser = cache(async () => {
  const session = await auth()
  return session ? db.user.findUnique({ where: { id: session.userId } }) : null
})

3.3 — Cross-request caching: unstable_cache/"use cache" or an LRU for data shared between users; always define revalidation (revalidateTag/revalidatePath) at write time.

3.4 — after() for non-blocking work — logging, analytics, notifications run after the response is sent.

3.5 — Never fetch your own API routes from Server Components. Call the data layer (DB/service) directly; the HTTP hop to yourself is pure overhead.

4. Client-Side Data Fetching (MEDIUM-HIGH)

4.1 — Use SWR (or React Query) instead of useEffect + fetch. Automatic dedupe, cache, revalidation, race-condition safety.

// ❌ manual effect fetch: no dedupe, races, no cache
useEffect(() => { fetch('/api/user').then(...) }, [])
// ✅
const { data, error, isLoading } = useSWR('/api/user', fetcher)

4.2 — Deduplicate global listeners — one resize/scroll listener shared via a small store or context, not one per component instance.

4.3 — Passive listeners for scroll/touch: addEventListener('scroll', fn, { passive: true }).

4.4 — Version localStorage payloads ({ v: 2, data }) and handle both parse failure and stale versions on read.

5. Re-render Optimization (MEDIUM)

5.1 — Never define components inside components. The inner component remounts on every render, losing state and DOM.

5.2 — Hoist non-primitive default props (const EMPTY: Item[] = []) outside the component — inline []/{}/() => {} defeats memoization.

5.3 — Extract expensive subtrees into memo() components and pass primitive props; prefer restructuring (move state down, pass children) over sprinkling useMemo everywhere.

5.4 — Effects should depend on primitives: useEffect(fn, [user.id]), not [user].

5.5 — startTransition for non-urgent updates (filtering large lists, tab switches) so typing stays responsive.

6. Rendering Performance (MEDIUM)

6.1 — content-visibility: auto for long lists, or virtualize (react-window/virtua) above ~200 rows.

6.2 — Prefer ternaries over && for conditional JSX — {count && <X/>} renders a literal 0.

6.3 — Extract static JSX outside the component so it's created once.

6.4 — Animate a wrapper <div> with CSS transforms, not SVG internals; keep animations on transform/opacity (compositor-only).

6.5 — Expected hydration mismatches (timestamps, locale) → suppressHydrationWarning on that node, or render client-only via useEffect-gated state.

7. JavaScript Micro-Performance (LOW-MEDIUM)

• Use Map/Set for repeated lookups instead of array.find/includes in loops (O(1) vs O(n)).
• Combine chained filter().map() into one pass when the list is large and hot.
• Batch DOM writes; toggle classes instead of many inline style mutations.
• requestIdleCallback for non-critical deferred work.

8. Next.js App Router Essentials

• generateMetadata for SEO; next/image always (never raw <img> for content images); next/font for zero-layout-shift fonts.
• Route handlers e páginas dinâmicas: declare export const dynamic/revalidate explicitly quando o default implícito não for óbvio.
• loading.tsx + error.tsx em toda rota com fetch — streaming UX e error boundary por segmento.
• Server Components por padrão; client components apenas onde há interatividade real.
• Mutations via Server Actions com revalidatePath/revalidateTag — não faça mutate + router.refresh() manual quando a action resolve.

Checklist de review (QA)

• Nenhum await sequencial de operações independentes
• Nenhum barrel import de libs de UI/ícones
• "use client" apenas em folhas interativas
• Server Actions autenticam e validam input
• Fetch client-side via SWR/React Query, não useEffect cru
• Nenhum componente definido dentro de componente
• Imagens via next/image, fontes via next/font
• Listas longas virtualizadas ou com content-visibility

Adaptado de vercel-labs/agent-skills → react-best-practices (skills.sh) — 2026-08-26. Seção 8 (Next.js) baseada em conhecimento próprio: a skill next-best-practices foi descontinuada (vercel-labs/next-skills arquivado; docs agora embutidas no framework).