Debugging Hydration Mismatches at Scale: A Production Playbook
You've seen the error: "Hydration failed because the initial UI does not match." We traced 23 unique causes across 8 production apps. Here's the full taxonomy.
Benchmark data, server component deep-dives, and ISR war stories pulled from real deploys. No opinions — only numbers and the post-mortems that explain them.
Click any row to read the post that produced this data. All metrics measured on identical hardware across 50 builds per configuration.
| Metric | v13 | v14 | v15 | |||
|---|---|---|---|---|---|---|
| Pages | App | Pages | App | Pages | App | |
Time to First Byte Network | 89ms | 112ms | 61ms | 54ms | 44ms | 38ms |
JS Bundle (P95) Performance | 187kb | 162kb | 141kb | 118kb | 108kb | 94kb |
Cold Build Time DX | 78s | 94s | 52s | 58s | 31s | 23s |
Lighthouse Score Quality | 82/100 | 79/100 | 88/100 | 91/100 | 93/100 | 97/100 |
Hydration Time Performance | 340ms | 280ms | 220ms | 170ms | 140ms | 95ms |
First Contentful Paint Network | 1.4s | 1.6s | 1.0s | 0.9s | 0.7s | 0.6s |
You've seen the error: "Hydration failed because the initial UI does not match." We traced 23 unique causes across 8 production apps. Here's the full taxonomy.
revalidatePath, revalidateTag, and on-demand ISR — when each fires, what it invalidates, and the edge cases that will bite you at 3 AM.
We migrated a 180k-line CRA codebase. Week-by-week notes, blockers, and the three decisions we'd make differently.
The 1MB limit, the Node.js API gaps, the cold start behavior — and why we still use it for auth.
We measured latency, bundle impact, and DX across 12 mutation patterns. The answer depends on your data layer.
PPR and streaming promise faster perceived load. We measured LCP, TBT, and INP across 6 page architectures.
A 180k-line SaaS dashboard migrated over 90 days. These are the production metrics, measured 30 days post-migration.
The Deploy app puts every migration guide, benchmark table, and code snippet in your pocket — no internet required.
Available on iOS, Android, and Desktop.