I migrated a medium-sized Next.js app from Pages Router to App Router about four months ago. I had been putting it off because every article I read said something different. Some said the App Router was the future and you should migrate now. Others said it was half-baked and to wait. Both camps were kind of right.<\/p>\n
Now that I’ve been living with it for a while: the App Router is better. But it’s a genuinely different mental model, not just an upgrade path, and there are specific things you’ll get wrong the first time.<\/p>\n
This is what I wish someone had told me before I started.<\/p>\n
Most explanations of The real change is that App Router is built around React Server Components. By default, every component in If you want client-side interactivity, you opt in explicitly with Pages Router is the opposite: every page is a client component by default. You use Here’s how that looks in practice:<\/p>\n The App Router version is shorter. But if you need state or user interaction, you split the component:<\/p>\n That split is the thing you’ll fight with for the first few weeks.<\/p>\n In Pages Router, data fetching is explicit and centralized. In App Router, any Server Component can just This is genuinely nice once you’re used to it. You stop thinking about “where do I put the data fetching” and just fetch where you need it. The downside is that data fetching can get scattered across the component tree, which takes discipline to keep organized.<\/p>\n The caching model also changed significantly. Pages Router has a relatively simple story: SSR means fresh data every request, SSG means build-time data. App Router has a granular caching system where you control caching at the individual fetch level:<\/p>\n More powerful than Pages Router. Also more footguns. The Next.js caching documentation<\/a> is worth reading before you ship anything to production \u2014 the default behavior isn’t always what you’d expect.<\/p>\n Based on my own migration and talking to others who’ve done it: the most common first mistake is putting too much in Client Components.<\/p>\n The pattern goes like this: you move a page to App Router, something breaks, you add That’s not fatal, but you’ve missed the performance benefits and the architectural point.<\/p>\n The right approach is pushing The second thing that catches people is passing non-serializable values from Server Components to Client Components. You can’t pass a function or a class instance as a prop across that boundary. Strings, numbers, plain objects \u2014 fine. Functions and complex objects \u2014 you’ll get an error. Restructuring around this is annoying but usually points you toward a cleaner design anyway.<\/p>\n If you’re migrating and want to understand how this affects form handling and mutations, I covered how Server Actions changed the way I think about API routes in a separate post \u2014 why I stopped writing API routes after Server Actions<\/a>. The two changes are related and fit together once you see them together.<\/p>\n If your project is actively developed and you’re planning to stay on Next.js long-term: yes. The App Router is where Next.js is going. Pages Router is in maintenance mode \u2014 it gets security fixes, not new features.<\/p>\nnextjs app router<\/code> vs Pages Router lead with the file system changes: move from \/pages\/<\/code> to \/app\/<\/code>, use page.tsx<\/code> files, add layout.tsx<\/code> for shared layouts. That stuff matters, but it’s not the conceptual shift.<\/p>\n\/app\/<\/code> is a Server Component \u2014 it renders on the server, sends HTML to the client, and ships no JavaScript for that component to the browser.<\/p>\n'use client'<\/code> at the top of the file.<\/p>\ngetServerSideProps<\/code> or getStaticProps<\/code> to pull in server-side data, but the component itself runs in the browser.<\/p>\n\/\/ pages\/dashboard.tsx \u2014 Pages Router (client component by default)\nimport { useState } from 'react'\n\nexport default function Dashboard({ initialData }) {\n const [data, setData] = useState(initialData)\n return <div>{data.title}<\/div>\n}\n\nexport async function getServerSideProps() {\n const data = await fetchDashboardData()\n return { props: { initialData: data } }\n}\n<\/code><\/pre>\n\/\/ app\/dashboard\/page.tsx \u2014 App Router (server component by default)\nasync function Dashboard() {\n const data = await fetchDashboardData() \/\/ direct async call, no special API\n return <div>{data.title}<\/div>\n}\n<\/code><\/pre>\n\/\/ app\/dashboard\/page.tsx\nimport DashboardClient from '.\/DashboardClient'\n\nasync function Dashboard() {\n const data = await fetchDashboardData()\n return <DashboardClient initialData={data} \/>\n}\n\n\/\/ app\/dashboard\/DashboardClient.tsx\n'use client'\nimport { useState } from 'react'\n\nexport default function DashboardClient({ initialData }) {\n const [data, setData] = useState(initialData)\n return <div>{data.title}<\/div>\n}\n<\/code><\/pre>\nData fetching: where it got confusing for me<\/h2>\n
getServerSideProps<\/code> for dynamic data, getStaticProps<\/code> for build-time data. One function, one place per page.<\/p>\nawait<\/code> a database call, an API call, whatever. No special API needed \u2014 it’s just async functions.<\/p>\n\/\/ Revalidate every hour\nconst data = await fetch('https:\/\/api.example.com\/data', {\n next: { revalidate: 3600 }\n})\n\n\/\/ No caching \u2014 always fresh\nconst data = await fetch('https:\/\/api.example.com\/data', {\n cache: 'no-store'\n})\n<\/code><\/pre>\nThe mistake everyone makes first<\/h2>\n
'use client'<\/code> at the top of the file, it works. You repeat this until everything works. By the end, your app is functionally equivalent to Pages Router \u2014 you’ve just moved files around.<\/p>\n'use client'<\/code> as far down the component tree as possible. Keep it on the interactive leaves \u2014 buttons, forms, inputs \u2014 and let everything above them stay as Server Components. This takes restructuring. The payoff is real: less JavaScript shipped to the client, faster initial loads, and a cleaner separation between data fetching and UI state.<\/p>\nShould you migrate an existing project?<\/h2>\n