Next.js App Router Migration Practical Guide — Pitfalls and Solutions When Transitioning to Server Components

Honestly, when I heard that our team running Pages Router had decided to switch to App Router, my first reaction was a sigh. Why touch code that's working fine? But after finishing the migration and looking back, it was more than a simple technology swap. Loading spinners disappeared throughout the app, a significant number of API endpoints we'd created for each page became unnecessary, and the risk of sensitive DB logic leaking into client responses was reduced. Bundle size also shrank noticeably, though the extent varies by project configuration.

This article targets developers who have experience running Next.js Pages Router. It may also help those considering a new project, but it primarily addresses the real-world friction that arises when migrating an existing codebase. getServerSideProps appears in the text — think of it as "a Pages Router-specific function that pre-fetches data on the server and injects it into page components."

Clearly designing where to draw the rendering boundary is the core of a Server Component migration. Here are the pitfalls I encountered firsthand — situations where misconfigured client component boundaries caused bundle sizes to grow even larger than in the Pages Router days, or where errors cascaded because the Context API doesn't work on the server.

Table of Contents

• Core Concepts
  • Rendering Boundary — The First Thing to Understand
  • Component Composition — The Rule That Trips You Up Most Early On
  • Streaming + Suspense — The Hidden Strength of Server Components
• Practical Application
  • Example 1: Replacing useEffect Data Fetching with Server Components
  • Example 2: Incremental Migration — Pages Router and App Router Coexistence
  • Example 3: Handling Third-Party Libraries
• Pros and Cons Analysis
  • Pros
  • Cons and Caveats
  • The Most Common Mistakes in Practice
• Closing Thoughts
• References

Core Concepts

Rendering Boundary — The First Thing to Understand

In the old Pages Router, every page component was effectively client-side code. Even when fetching data on the server with getServerSideProps, the component itself was included in the client JS bundle. App Router flips this default. Files inside the app/ directory are Server Components by default, and only files that declare 'use client' become Client Components.

// app/products/page.tsx — Server Component (default)
// The code in this file is NOT included in the client bundle
export default async function ProductsPage() {
  // In production code, it is recommended to verify authentication/authorization (e.g., session checks) before access
  const products = await db.product.findMany();
  return <ProductList products={products} />;
}
 
// components/AddToCartButton.tsx — Client Component
'use client';
export function AddToCartButton({ productId }: { productId: string }) {
  const [added, setAdded] = useState(false);
  return (
    <button onClick={() => setAdded(true)}>
      {added ? 'Added' : 'Add to Cart'}
    </button>
  );
}

Server Component: A React component that runs only on the server and delivers only the resulting HTML to the client. It cannot use client hooks like useState or useEffect, but in return it can directly access databases, use secret keys, and access the file system.

Component Composition — The Rule That Trips You Up Most Early On

I personally wasted half a day on this rule. What made it even more confusing was that importing a Server Component from a file marked 'use client' doesn't always immediately throw an error.

To be precise, the import itself is technically possible, but the module gets included in the client bundle and loses its Server Component properties. The runtime error only fires the moment a server-only API like headers() or cookies() is called. If you miss this, it looks like "an error that appears occasionally," making debugging all the more frustrating.

The solution is to use a composition pattern where Server Components are injected as slots via the children prop.

// ❌ This causes the Server Component to lose its properties
'use client';
import { ServerOnlyComponent } from './ServerOnlyComponent';
// If ServerOnlyComponent uses headers() or cookies(), a runtime error will occur
 
// ✅ The correct pattern: inject via children
'use client';
export function ClientWrapper({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
      {/* Pre-rendered server content goes here */}
      {isOpen && children}
    </div>
  );
}
 
// app/page.tsx — Server Component
import { ClientWrapper } from './ClientWrapper';
import { ServerData } from './ServerData'; // Server Component
 
export default function Page() {
  return (
    <ClientWrapper>
      <ServerData /> {/* Passing Server Component as children */}
    </ClientWrapper>
  );
}

When you first encounter this pattern, you might think "why does it have to be this complicated?" But once you get used to it, the server/client boundary becomes much more visible in the code.

Streaming + Suspense — The Hidden Strength of Server Components

This feature deserves more than a single line in the pros table. With the old approach, the first screen couldn't appear until all of the page's data was ready. With Streaming, faster data can be shown first in order.

In App Router, a single loading.tsx file automatically creates a Suspense boundary.

// app/dashboard/loading.tsx — Automatic Suspense fallback handling
export default function Loading() {
  return <DashboardSkeleton />;
}
 
// app/dashboard/page.tsx
export default async function Dashboard() {
  // While this await completes, the skeleton from loading.tsx is displayed
  const analytics = await fetchAnalytics();
  return <AnalyticsView data={analytics} />;
}

If you want finer-grained control per section, you can also wrap directly with the <Suspense> component. For a dashboard page with a slow query, showing faster sections first without waiting for everything to be ready produces quite a dramatic improvement in perceived performance.

Practical Application

Example 1: Replacing useEffect Data Fetching with Server Components

This is the transformation with the most immediate impact in a migration. The useEffect + fetch combination necessarily shows a loading spinner because data isn't requested until after the component mounts. With Server Components, this step disappears entirely.

// Before: Client fetching — included in bundle, triggers an additional request after mount
'use client';
export function UserProfile({ userId }: { userId: string }) {
  // The angle brackets in useState<User | null> are TypeScript generics — specifying that the state holds User or null
  const [user, setUser] = useState<User | null>(null);
 
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(setUser);
  }, [userId]);
 
  if (!user) return <Spinner />;
  return <div>{user.name}</div>;
}
 
// After: Server Component — direct DB access, zero bundle cost, no spinner
export async function UserProfile({ userId }: { userId: string }) {
  const user = await db.user.findUnique({ where: { id: userId } });
  // If no matching user exists in the DB, handle as 404 with notFound()
  if (!user) notFound();
  return <div>{user.name}</div>;
}

Example 2: Incremental Migration — Pages Router and App Router Coexistence

A Big Bang approach that rewrites a large project all at once is risky. The strategy officially recommended by Vercel is to add an app/ directory while leaving the existing pages/ intact.

project/
├── pages/           # Existing Pages Router — works as-is
│   ├── _app.tsx
│   ├── about.tsx
│   └── contact.tsx
├── app/             # Newly added App Router
│   ├── layout.tsx
│   └── dashboard/   # Newly migrated page
│       └── page.tsx
└── next.config.ts

The approach is to move pages one by one into app/. However, navigating from a Pages Router page to an App Router page (or vice versa) can cause a full page load, creating a UX disruption. Grouping pages that are frequently navigated between under the same router when planning migration order minimizes this issue.

Example 3: Handling Third-Party Libraries

A situation frequently encountered in practice — libraries that directly reference window or document will throw errors in Server Components. Visualization libraries like Lottie and react-force-graph are prime examples. Wrapping with next/dynamic lets you load them only on the client without SSR.

// components/ChartWrapper.tsx
import dynamic from 'next/dynamic';
import type { ChartData } from './HeavyChart'; // Types can be imported on the server as well
 
// ssr: false — not rendered on the server, loaded only on the client
const HeavyChart = dynamic(
  () => import('./HeavyChart'),
  {
    ssr: false,
    loading: () => <div>Loading chart...</div>,
  }
);
 
export function ChartWrapper({ data }: { data: ChartData }) {
  return <HeavyChart data={data} />;
}

Pros and Cons Analysis

Pros

Of these, the two with the greatest real-world impact were "no API endpoints needed" and "security isolation." There's no need to create separate REST endpoints for DB access logic, and the worry of secret keys leaking into network responses is reduced.

Cons and Caveats

The one that blindsided me most was the Context API limitation. In an app managing global state with Context, unexpected errors cascaded one after another, and it took considerable time just to find the root cause. Knowing this in advance would have saved at least a day.

Hydration: The process of attaching client-side JavaScript to server-generated HTML to make it interactive. If the server and client rendering results differ, React will re-render the entire tree.

The Most Common Mistakes in Practice

1. Setting the client component boundary too high — Adding 'use client' at the top of a page causes all child components to be treated as client-side. Taking this approach early on resulted in bundle sizes that actually grew larger than in the Pages Router days. The key is to place the boundary only on the smallest unit of component that requires interactivity.

2. Trying to use Context API in Server Components as-is — Failing to audit the global state management structure in advance causes errors to cascade during migration. Drawing up a list of Context Providers before starting and planning to move each one to a 'use client' file reduces this pain.

3. Converting manually without codemods — Next.js official codemods automatically handle repetitive tasks like converting getServerSideProps and updating next/link syntax. Even a modestly sized codebase accumulates mistakes with manual conversion.

# Run official codemod — automates mechanical conversion tasks
npx @next/codemod@latest upgrade latest

Closing Thoughts

After completing a migration, you're left with both the thought "I wish I'd done this sooner" and the regret "I wish I'd known about these pitfalls in advance." It comes down to two core principles: clearly designing the server/client boundary, and minimizing the scope of Client Components — these two principles serve as your compass throughout the migration. Everything else is specific challenges you encounter while consistently applying those principles.

Three steps you can start with right now:

1. Search your current project for the useEffect + fetch pattern. Use a global search to list components containing useEffect, then identify which ones could be handled server-side. This list becomes your first round of migration candidates.
2. Add an app/ directory and move the simplest page first. Running the codemod first will show you that a significant portion of the mechanical conversion work is reduced.
3. Use React DevTools and next/bundle-analyzer to compare before and after. Verify that no server-only code has leaked into the client bundle, and measure TTFB and LCP improvement with Lighthouse or Web Vitals — this helps prioritize the next migration targets. In a Vercel environment, Speed Insights can also be used alongside these tools.

Next post: State management patterns for using Zustand and Jotai together with Server Components — a concrete design approach where the server injects initial values and the client store holds only interaction state

References

• React Server Components Migration Guide | Dev Radar
• Next.js App Router Migration Best Practices 2026 | WebCraftDev
• Next.js 15 & 16 Features: Complete Migration Guide | Jishu Labs
• React Server Components: Practical Guide 2026 | inhaq.com
• Critical Security Vulnerability in React Server Components | react.dev
• Migrating to the Next.js App Router | Money Forward Developers Blog
• Next.js App Router Migration: The Good, Bad, and Ugly | Flightcontrol
• How to Migrate from Pages to the App Router | Next.js Official Docs
• Rendering: Composition Patterns | Next.js Official Docs
• Upgrading: Codemods | Next.js Official Docs
• Making Sense of React Server Components | Josh W. Comeau
• Turbopack in 2026: The Complete Guide | DEV Community
• Component Composition Patterns | Vercel Academy
• Next.js 16 Upgrade Guide | Next.js Official Docs