skills.rest
gonzoblasco
gonzoblascoCOMMUNITY
Explore all skills by this author →
𝕏@gonzoblascoGitHub

nextjs-production-debugger

Diagnose Next.js App Router production issues including hydration errors, runtime mismatches, and caching layers.

1|Updated Jul 20, 2026
Search Tags:#debugging#caching#production#nextjs#ssr#app router#hydration
One-click install
npx skills add https://github.com/gonzoblasco/ai-developer-stack --skill nextjs-production-debugger-gonzoblasco
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nextjs-production-debugger
Source: https://github.com/gonzoblasco/ai-developer-stack/tree/main/frontend-ui/nextjs-production-debugger
Command: npx skills add https://github.com/gonzoblasco/ai-developer-stack --skill nextjs-production-debugger-gonzoblasco

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Production bugs in Next.js App Router apps are hard to isolate because failures can originate in server rendering, client hydration, runtime environments, or one of four caching layers. This Skill provides structured diagnostic tables and fixes to pinpoint and resolve these issues quickly. ## Core Features & Use Cases - SSR vs CSR Isolation: Decision tables and techniques (disabling JavaScript, hard refresh) to determine whether a bug lives on the server or the client. - Hydration Error Debugging: Identifies common causes like Date.now() in render bodies, invalid HTML nesting, and window checks, with fixes such as useEffect and suppressHydrationWarning. - Runtime and Cache Troubleshooting: Covers Edge vs Node runtime mismatches (e.g., 'fs' module errors in Middleware) and the four Next.js cache layers (Request Memoization, Data Cache, Full Route Cache, Router Cache) with revalidation fixes. - Use Case: Your page shows stale data after a database update. Follow the cache debug flow to determine whether the culprit is the client Router Cache, Data Cache, or Full Route Cache, then apply revalidatePath or force-dynamic accordingly. ## Quick Start Ask the assistant to diagnose why your Next.js page shows a hydration error or stale data in production using the nextjs-production-debugger guidelines.

Frequently Asked Questions about nextjs-production-debugger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix hydration errors in Next.js App Router?▼

Hydration errors usually come from non-deterministic values like Date.now() or Math.random() in the render body, or invalid HTML such as a div inside a p tag. Move client-dependent logic into useEffect, validate your HTML, or use suppressHydrationWarning for cosmetic-only cases.

How to tell if a Next.js bug is server-side or client-side?▼

Disable JavaScript in the browser and reload: if the content is broken without JS, the bug is in server rendering and you should check terminal logs. If the page loads fine but fails during interaction or navigation, check the browser console and React DevTools.

Why does Next.js show stale data after a database update?▼

Next.js has four cache layers: Request Memoization, Data Cache, Full Route Cache, and the client Router Cache. Use fetch with cache no-store or export const dynamic force-dynamic for real-time data, and call revalidatePath in Server Actions or router.refresh() to invalidate caches.

Why does Next.js Middleware fail with Module not found fs?▼

Middleware always runs in the Edge Runtime, which lacks Node.js APIs like fs. Use Web Standard APIs such as fetch, Request, and Response instead, or move Node-dependent code to a route with export const runtime nodejs.

How do I fix slow page loads in Next.js App Router?▼

Slow loads usually come from fetch waterfalls or blocking server requests. Parallelize fetches with Promise.all, avoid making entire pages client components, and wrap slow server sections in Suspense with a Skeleton fallback to enable Streaming SSR.

Related Skills

Explore More Software Engineering Skills→
cosmicstack-labscosmicstack-labs
364

nextjs-patterns

Establish Next.js App Router and Server Component patterns for full-stack React applications.

Official
Intermediate
timurgaleevtimurgaleev
5

canary

Monitor post-deploy web apps for defects and performance regressions.

Community
Advanced
ihj04982ihj04982

prevent-hydration-mismatch-without-flickering

Inject a synchronous script to update the DOM before React hydration.

Community
Basic
hopeoverturehopeoverture
6

sentry-and-otel-setup

Configure Sentry and OpenTelemetry error tracking and performance monitoring for Next.js applications.

Community
Advanced