Migrating to Next.js App Router: A Developer's Journey

Jan 2024

Migrating to Next.js App Router: A Developer's Journey

The Next.js App Router represents a significant evolution in how we build React applications. After migrating several production applications from the Pages Router to the new App Router, I want to share the lessons learned, challenges faced, and the substantial benefits gained.

Why Migrate to App Router?

The App Router isn't just a new routing system—it's a fundamental shift toward modern React patterns and improved developer experience.

Key Benefits

  • Server Components by default - Better performance and SEO
  • Improved data fetching - Colocation of data and UI components
  • Enhanced layouts - Nested layouts with shared state
  • Better TypeScript support - Improved type inference and safety
  • Streaming and Suspense - Progressive page loading

The Migration Process

1. Understanding the New Structure

The most significant change is the file-based routing system:

// Pages Router (old)
pages/
  index.js          → /
  about.js          → /about
  blog/
    index.js        → /blog
    [slug].js       → /blog/[slug]

// App Router (new)  
app/
  page.js           → /
  about/
    page.js         → /about
  blog/
    page.js         → /blog
    [slug]/
      page.js       → /blog/[slug]

2. Component Migration Strategy

Start with leaf pages and work your way up:

// Before: pages/blog/[slug].tsx
export default function BlogPost({ post }) {
  return <article>{post.content}</article>
}

export async function getStaticProps({ params }) {
  const post = await getPost(params.slug)
  return { props: { post } }
}

// After: app/blog/[slug]/page.tsx
export default async function BlogPost({ params }) {
  const post = await getPost(params.slug)
  return <article>{post.content}</article>
}

3. Layout Migration

One of the most powerful features is the nested layout system:

// app/layout.tsx (Root Layout)
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Header />
        <main>{children}</main>
        <Footer />
      </body>
    </html>
  )
}

// app/blog/layout.tsx (Blog Layout)
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="blog-container">
      <BlogSidebar />
      <div className="blog-content">
        {children}
      </div>
    </div>
  )
}

Challenges and Solutions

Challenge 1: Client vs Server Components

Problem: Understanding when to use "use client" directive.

Solution: Start with Server Components by default, add "use client" only when you need:

  • Event handlers
  • Browser-only APIs
  • State management
  • Effects
// Server Component (default)
export default async function PostList() {
  const posts = await getPosts()
  return (
    <div>
      {posts.map(post => (
        <PostCard key={post.id} post={post} />
      ))}
    </div>
  )
}

// Client Component (when needed)
"use client"
export default function SearchBox() {
  const [query, setQuery] = useState('')
  
  return (
    <input 
      value={query}
      onChange={(e) => setQuery(e.target.value)}
    />
  )
}

Challenge 2: Data Fetching Patterns

Problem: Replacing getStaticProps and getServerSideProps.

Solution: Use async Server Components and new caching strategies:

// Old pattern
export async function getStaticProps() {
  const data = await fetchData()
  return { props: { data } }
}

// New pattern
export default async function Page() {
  const data = await fetchData() // Automatically cached
  return <div>{data.title}</div>
}

// With custom caching
const getData = cache(async () => {
  return await fetchData()
})

Challenge 3: Metadata Management

Problem: Migrating from next/head to the new metadata API.

Solution: Use the new metadata export:

// Old way
import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My Page</title>
        <meta name="description" content="Page description" />
      </Head>
      <div>Content</div>
    </>
  )
}

// New way
export const metadata = {
  title: 'My Page',
  description: 'Page description',
}

export default function Page() {
  return <div>Content</div>
}

Performance Improvements

After migration, we observed significant improvements:

  • First Contentful Paint: 40% faster
  • Largest Contentful Paint: 35% faster
  • Time to Interactive: 50% faster
  • Bundle size: 25% smaller

Best Practices Learned

1. Gradual Migration

Don't migrate everything at once. Use the app and pages directories side by side during transition.

2. Component Composition

Leverage Server Components for data fetching and Client Components for interactivity:

// Server Component handles data
export default async function BlogPage() {
  const posts = await getPosts()
  
  return (
    <div>
      <SearchBox /> {/* Client Component */}
      <PostList posts={posts} /> {/* Server Component */}
    </div>
  )
}

3. Error Boundaries

Use the new error handling patterns:

// app/blog/error.tsx
'use client'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Tools and Resources

Essential Tools

  • Next.js Codemod - Automated migration assistance
  • React DevTools - Server/Client component debugging
  • TypeScript - Enhanced type safety

Helpful Commands

# Run codemods for automatic migration
npx @next/codemod@latest app-router-migration

# Check bundle analyzer
npm run build && npm run analyze

Conclusion

Migrating to Next.js App Router requires careful planning and understanding of the new paradigms, but the benefits are substantial. The improved performance, better developer experience, and modern React patterns make it a worthwhile investment.

The key is to approach the migration incrementally, understand the Server/Client Component distinction, and leverage the new data fetching patterns effectively.

Pro tip: Start with a small, non-critical section of your app to get familiar with the patterns before migrating your entire application.

Have you migrated to App Router? Share your experience and challenges in the comments below or reach out on LinkedIn.

Edoardo Armandi