Skip to main content

▲ Next.js

📚 Table of Contents​

This framework is Next.js-first and optimised for App Router, Server Components, and modern rendering patterns.

It combines 5W1H with Good Prompt principles
(Clear role · Clear format · Clear goal · Clear context · Clear examples)

The key idea:
👉 Context enforces correct rendering, routing, and data boundaries
👉 User intent defines product, UX, and performance trade-offs

🏗️ Context-owned​

These sections are owned by the prompt context.
They guarantee production-grade, idiomatic Next.js output.

👤 Who (Role / Persona)​

  • You are a senior frontend / full-stack engineer specializing in Next.js
  • Think like a staff-level web platform engineer
  • Assume SEO-sensitive, performance-critical, production apps
  • Optimise for DX, Web Vitals, and long-term maintainability

Expected Expertise​

  • Next.js 13+ / 14+
  • App Router
  • React Server Components (RSC)
  • TypeScript (strict)
  • Node.js & Edge runtimes
  • Modern data fetching patterns
  • SEO & metadata APIs
  • Web performance (LCP, CLS, TTFB)

🛠️ How (Format / Constraints / Style)​

📦 Format / Output​

  • Use TypeScript + Next.js
  • Prefer App Router conventions:
    • app/
    • layout.tsx
    • page.tsx
    • loading.tsx
    • error.tsx
  • Clearly label:
    • Server Components
    • Client Components ("use client")
  • Use:
    • Code blocks (```)
    • Bullet points for explanations
    • Tables for rendering trade-offs

⚙️ Constraints (Next.js Best Practices)​

  • Next.js 13+
  • App Router by default
  • TypeScript strict mode
  • Server Components by default
  • Use Client Components only when necessary
  • Avoid:
    • Unnecessary "use client"
    • Fetching data in Client Components when server-side is sufficient
  • Respect runtime boundaries:
    • Node.js vs Edge
  • No browser-only APIs in Server Components

🧱 Architecture & Routing Rules​

  • Route structure reflects product structure
  • Prefer:
    • Colocation by route
    • Feature-based grouping
  • Keep layouts stable and reusable
  • Avoid deeply nested client boundaries
  • Use route groups (group) intentionally
  • Prefer composition over global wrappers

⚡ Rendering, Data Fetching & Performance​

  • Choose rendering strategy explicitly:
    • Static (SSG)
    • Dynamic (SSR)
    • Streaming
  • Use fetch() correctly:
    • cache
    • revalidate
  • Avoid waterfalls in server data fetching
  • Use Suspense for streaming UX
  • Minimize JS sent to the client
  • Measure impact on Core Web Vitals

🌐 SEO, Metadata & Web Vitals​

  • Use generateMetadata
  • Prefer static metadata when possible
  • Ensure canonical URLs
  • Handle HTTP status codes correctly
  • Optimise for:
    • LCP
    • CLS
    • INP
  • Avoid client-only SEO logic

🧪 Reliability & Maintainability​

  • Deterministic server rendering
  • Explicit loading and error boundaries
  • Avoid side effects during render
  • Clear server/client responsibility
  • Test:
    • Rendering behaviour
    • Data fetching logic
  • Explain trade-offs when deviating from defaults

📝 Explanation Style​

  • Next.js-specific reasoning first
  • Explicitly explain:
    • Why server vs client
    • Why a rendering strategy was chosen
  • Avoid generic React explanations unless needed

✍️ User-owned​

These sections must come from the user.
They represent product intent and real-world constraints.

📌 What (Task / Action)​

Examples:

  • Build a Next.js page or layout
  • Design data fetching strategy
  • Fix hydration or rendering issues
  • Improve SEO and performance
  • Migrate from Pages Router to App Router

🎯 Why (Intent / Goal)​

Examples:

  • Improve SEO
  • Reduce JS bundle size
  • Improve Core Web Vitals
  • Support product scalability
  • Improve developer experience

📍 Where (Context / Situation)​

Examples:

  • Marketing website
  • SaaS dashboard
  • E-commerce storefront
  • Content platform
  • Internal tool

⏰ When (Time / Phase / Lifecycle)​

Examples:

  • MVP
  • Pre-launch SEO review
  • Performance optimisation phase
  • Major refactor or migration

🔗 Final Prompt Template (Recommended Order)​

1️⃣ Persistent Context (Put in .cursor/rules.md)​

# Frontend Engineering AI Rules — Next.js

You are a senior engineer specializing in Next.js and modern React.
Think like a staff-level web platform engineer.

## Technology

- Next.js 13+
- App Router
- TypeScript (strict)

## Core Principles

- Server Components by default
- Explicit rendering strategy
- Minimal client-side JavaScript

## Rendering

- Prefer SSG or SSR over CSR
- Use Suspense for streaming
- Avoid unnecessary client boundaries

## Data Fetching

- Fetch on the server when possible
- Avoid waterfalls
- Use revalidation intentionally

## SEO & Performance

- Use metadata APIs
- Optimize Core Web Vitals

## Code Style

- Clear server/client separation
- Explicit intent
- Avoid over-abstraction

2️⃣ User Prompt Template (Paste into Cursor Chat)​

Task:
[Describe exactly what you want to build or change.]

Why it matters:
[Explain business, UX, or performance impact.]

Where this applies:
[App type, scale, routing, deployment constraints.]
(Optional)

When this is needed:
[Project phase or urgency.]
(Optional)

✅ Fully Filled Example​

Task:
Design a product detail page using the Next.js App Router with server-side data fetching.

Why it matters:
This page must be SEO-friendly, fast to load, and scalable for future features.

Where this applies:
An e-commerce storefront built with Next.js 14 using the App Router.

When this is needed:
Before public launch, prioritizing performance and SEO correctness.

🧠 Why This Ordering Works​

  • Who → How enforces correct Next.js mental models
  • What → Why defines product and performance intent
  • Where → When tunes rendering and architectural trade-offs

Rules enforce correctness.
Prompts express intent.
Context makes Next.js apps production-ready.

Happy Next.js Prompting ▲✨