What I learned migrating to Next.js App Router

Migrating from the legacy Next.js Pages Router to the modern App Router is one of the most significant architectural paradigm shifts in modern frontend development. In this post, I want to share the practical engineering lessons, performance gains, and subtle bugs I encountered while migrating this portfolio and my other full-stack projects to Next.js 16 and React 19.

🚀 The Paradigm Shift: React Server Components (RSC)

In Pages Router, every component was loaded, hydrated, and rendered on the client. With App Router, components are Server Components by default. This means they render on the server first, and only their compiled HTML and server data payload are sent to the client.

This delivers huge performance benefits:

Smaller Client Bundle Size: None of the backend dependencies (like gray-matter or fs file-system logic) ever make it to the user's browser bundle.
Blistering-Fast FCP (First Contentful Paint): Pages are instantly readable because the browser receives pre-rendered static content immediately.

⚡ Turbopack vs. Webpack

During this migration, I fully committed to using Next.js's new Turbopack build engine (next dev --turbo). The local development experience is night and day:

Startup Speeds: The dev server boots in under 2 seconds.
HMR (Hot Module Replacement): Code changes reflect in the browser almost instantly, regardless of project scale.

However, Turbopack can occasionally accumulate memory when left active during long development sessions with aggressive fast-refresh cycles. When paired with real-time console streaming hooks, Node's old space limit can be hit. I resolved this in this workspace by setting: cross-env NODE_OPTIONS=--max-old-space-size=4096 next dev to guarantee plenty of execution space during long code-and-test marathons!

⚠️ The Battle with Hydration Mismatches

The most common issue when migrating to App Router is the dreaded Hydration Mismatch: Error: Hydration failed because the server rendered text didn't match the client...

This occurs because React 19 expects the initial client-rendered HTML to match the server-rendered HTML down to the exact character. Any dynamic data calculated during render (like local timezone timestamps or random generators) will break this match.

The Problem: Dynamic UTC Time Clocks

On this portfolio, I wanted to display a live UTC clock in the footer:

// This fails because Server calculates UTC on compilation, while 
// Client calculates local clock time upon loading!
export default function Footer() {
  const timeStr = new Date().getUTCHours();
  return <span>{timeStr}</span>;
}

The Solution: The Double-Render Mount Pattern

To solve this cleanly, we defer rendering dynamic client-only content until the component is fully mounted in the browser using a simple client-side check:

"use client";

import { useState, useEffect } from "react";

export default function FooterClock() {
  const [mounted, setMounted] = useState(false);
  
  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) {
    // Return a stable loading placeholder to match server HTML
    return <span>--:-- UTC</span>;
  }

  // Once mounted, it is safe to calculate dynamic client-only data
  const timeStr = new Date().toLocaleTimeString();
  return <span>{timeStr}</span>;
}

💡 Summary Checklist for App Router Migrations

Decide boundaries early: Use Server Components for all data fetching and Static Site Generation (SSG); use Client Components ("use client") only for interactive states, animations, and event hooks.
Defend against hydration errors: Wrap dynamic clocks, localized date displays, or random values in client-only mount loops.
Optimize layouts: Enforce min-w-0 on nested flex/grid elements to prevent third-party components (like Recharts) from triggering height-calculation exceptions during initial layout sweeps.