nextjs-rendering-runtime-and-middleware

Next.js Rendering Runtime and Middleware

Use this skill when the task is primarily about rendering model, runtime placement, or request interception before the route completes.

Scope

• Server Components vs Client Components as rendering boundaries
• static, dynamic, and streamed rendering choices
• route segment config and runtime selection
• Node.js vs Edge runtime tradeoffs
• proxy.ts and matcher-based request interception
• migration framing from legacy middleware.ts naming

Routing cues

• rendering mode, streaming, component runtime split, route segment config, Node vs Edge, or middleware / proxy questions -> use this skill
• data reads and cache invalidation as the primary concern -> use nextjs-data-fetching-and-cache
• mutation flow or Route Handlers as the primary concern -> use nextjs-server-actions-and-route-handlers
• metadata and sitemap surfaces as the primary concern -> use nextjs-metadata-seo-and-file-conventions

Default path

1. Read references/rendering-runtime-and-proxy.md first.
2. Decide the rendering boundary before adding 'use client' or Edge runtime flags.
3. Keep proxy.ts narrow and matcher-driven. Route endpoint logic elsewhere.
4. Choose runtime based on platform constraints, package support, and latency goals, not fashion.

When to deviate

• Add 'use client' only when state, effects, refs, or browser APIs force a client boundary.
• Use Edge runtime only when latency, geography, or platform constraints justify the narrower compatibility surface.
• Reach for proxy.ts only when the request truly needs interception before the route completes.
• Move to the data or server-boundary skills when rendering is no longer the main decision surface.

Quick example

export const runtime = 'edge'

Guardrails

• Server Components are the default. Client Components are an opt-in boundary.
• Do not use proxy.ts as a general replacement for Route Handlers or app business logic.
• The middleware file convention is deprecated; use proxy.ts / proxy.js terminology and file naming.
• Edge runtime compatibility is narrower than Node.js. Verify package support before moving code there.
• Prefer explicit matcher rules and keep interception logic easy to reason about.