playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / rendering

rendering skill

/skills/nextjs/rendering

This skill helps you choose and apply Next.js rendering strategies (SSG, SSR, ISR, Streaming, and PPR) to balance data freshness and performance.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill rendering

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.6 KB
---
name: Next.js Rendering Strategies
description: SSG, SSR, ISR, Streaming, and Partial Prerendering (PPR).
metadata:
  labels: [nextjs, rendering, isr, ssr, ssg]
  triggers:
    files: ['**/page.tsx', '**/layout.tsx']
    keywords: [generateStaticParams, dynamic, dynamicParams, PPR, streaming]
---

# Rendering Strategies (App Router)

## **Priority: P0 (CRITICAL)**

Choose rendering strategy based on data freshness and scaling needs. See [Strategy Matrix](references/strategy-matrix.md).

## Guidelines

- **SSG (Default)**: Build-time render. Use `generateStaticParams`.
- **SSR**: Per-request render. Triggered by `cookies()`, `headers()`, or `cache: 'no-store'`.
- **Streaming**: Wrap slow components in `<Suspense>` to avoid blocking.
- **ISR**: Post-build updates. Use `revalidate` (time) or `revalidatePath` (on-demand).
- **PPR**: Static shell + dynamic holes. Experimental `ppr` config.
- **Runtime**: Node.js (Full) or Edge (Lighter/Faster).

## Scaling & Hydration

- **Static Shell**: Render layout as static, personalize via Suspense.
- **Error Boundaries**: Use `error.tsx` with `reset()` to catch runtime errors.
- **Hydration Safety**: Avoid `typeof window` or `Date.now()` in initial render. Use `useEffect`.

## Anti-Patterns

- **No Root Awaits**: Avoid waterfalls in `page.tsx`. Use Streaming.
- **Bailouts**: Understand [Suspense Bailout Rules](references/SUSPENSE_BAILOUT.md).

## References

- [Strategy Selection Matrix](references/strategy-matrix.md)
- [Implementation Details](references/implementation-details.md)
- [Scaling Patterns](references/scaling-patterns.md)

Overview

This skill documents Next.js App Router rendering strategies: SSG, SSR, ISR, Streaming, and Partial Prerendering (PPR). It guides choice based on data freshness, performance, and scaling needs. The content focuses on concrete patterns, pitfalls, and practical configuration tips for production apps.

How this skill works

The skill inspects route code and runtime signals to determine the rendering mode: build-time generation (SSG), per-request server render (SSR), incremental updates (ISR), streamed partials, or PPR experimental shells. It highlights triggers like cookies(), headers(), cache settings, revalidate values, Suspense usage for streaming, and runtime target (node vs edge). It also surfaces scaling and hydration concerns and common anti-patterns to avoid.

When to use it

  • Use SSG for stable content where build-time HTML is acceptable and fastest delivery is required.
  • Use SSR when each request needs fresh, user-specific data or when cookies/headers must be read on the server.
  • Use ISR to keep mostly-static pages fresh without full rebuilds—use revalidate for time-based or revalidatePath for on-demand updates.
  • Use Streaming for large pages or slow data sources to render fast interactive shells and stream slow parts via <Suspense>.
  • Use PPR when you want a static shell with runtime dynamic holes (experimental) to combine stability and personalization.

Best practices

  • Default to SSG and opt-in to SSR/ISR only when necessary to minimize server cost and complexity.
  • Wrap slow client components in <Suspense> and render static shell first to improve Time to First Byte and hydration experience.
  • Avoid top-level awaits in page.tsx to prevent waterfall blocking; prefer streaming and splitting data fetching.
  • Keep runtime-safe code for initial render: don’t call Date.now() or inspect window during SSR—use useEffect for client-only logic.
  • Use error.tsx boundaries with reset() to handle runtime component failures gracefully and avoid full-page crashes.

Example use cases

  • Marketing landing pages and documentation: SSG for max CDN performance and low cost.
  • User dashboards requiring session data: SSR to read cookies and return tailored content per request.
  • News sites or catalogs: ISR with revalidate to update content frequently without full rebuilds.
  • Complex e-commerce product pages: Streaming to show layout and key content fast while images or recommendations stream in.
  • Personalized home page: PPR experimental pattern to ship static layout and fill dynamic regions at runtime.

FAQ

How do I trigger SSR instead of SSG?

SSR is triggered when server-only signals are used, such as cookies(), headers(), or cache: 'no-store' in the route code.

When should I use ISR vs revalidatePath on-demand?

Use time-based revalidate for predictable refresh cadence; use revalidatePath when you need immediate, on-demand updates after specific events (e.g., CMS publish).