Migrating a massive SaaS from Next.js Pages to App Router: The good, bad, and ugly
When Next.js introduced the App Router and React Server Components (RSC), the pitch sounded revolutionary: zero bundle size for backend utilities, streaming HTML responses, and unified data fetching. We decided to migrate a 90-page customer portal from Pages router (getServerSideProps) to App Router. Here is the unvarnished reality of what that migration felt like in production.
The mental shift: Client vs Server components
The hardest part was not the code change; it was training the team to think in terms of component boundaries. In the Pages router, an entire page was either client-rendered or server-hydrated. In App Router, you weave server components around tiny client islands.
Our biggest initial mistake was plastering "use client" at the top of entire directory layouts whenever an interactive element like a dropdown was needed. That completely negated the benefits of server components. We learned to push interactivity down to the leaves of the DOM tree.
The caching minefield
Next.js App Router has aggressive caching defaults across Data Cache, Full Route Cache, and Router Cache. In our early builds, users would update their profile details, refresh the dashboard, and still see their old company name.
Understanding fetch caching semantics required a total re-audit of our API calls:
- Explicitly declaring cache tags with `revalidateTag` on mutations - Avoiding accidental caching of dynamic cookies and request headers - Setting `export const dynamic = "force-dynamic"` on authenticated portal pages that must never serve stale shared HTML
Tangible performance wins
Once the architecture stabilized, the results justified the struggle:
- Client JavaScript bundle sent over the wire dropped by 42% - First Contentful Paint (FCP) improved from 1.8s to 0.7s on mobile networks - Sensitive API secrets and database client libraries were completely removed from client-accessible bundles
App Router is worth the investment for complex applications, but treat the migration as an architectural rewrite rather than a drop-in upgrade.
Have a similar challenge?
We build production-grade software for companies that need it done right.
Let's Talk
