Short version for the impatient: the Next.js App Router was worth the migration, but not for the reasons the launch posts sold me on. If you want the long version, and the two things that genuinely annoyed me along the way, keep reading.<\/p>\n
I put off moving a real production app off the Pages Router for about a year. Not because I doubted the App Router. It was more that “rewrite your routing layer” is the kind of sentence that suddenly makes fixing flaky tests sound fun. Then a client project forced my hand. They wanted streaming, per-section loading states, and a layout that didn’t throw away the sidebar’s state on every navigation. The Pages Router can fake some of that. It can’t do it cleanly. So I blocked off a weekend and moved the whole thing.<\/p>\n
Here’s what actually changed, with the before-and-after code, and where I’d tell you to slow down.<\/p>\n
The file moves are trivial. Once that landed for me, the rest of the migration stopped feeling like a fight. I wasn’t porting This is the change that sold me. Here’s a typical Pages Router page that loads a user’s dashboard:<\/p>\n There’s a whole serialization dance hiding in there. The data gets fetched on the server, JSON-stringified into the page’s props, shipped to the client, and rehydrated. For a big dashboard that props payload gets heavy fast.<\/p>\n The App Router version drops the ceremony:<\/p>\n The component is If you’re already reaching for a mutation after this, that’s Server Actions territory, and I wrote up how I stopped hand-rolling API routes for those in my post on Next.js Server Actions<\/a>.<\/p>\n The Pages Router never had a real answer for nested layouts. The community settled on a The App Router makes layouts a first-class file. A Navigate from Now the annoying part, because I promised honesty.<\/p>\n The App Router caches aggressively by default, and the defaults changed more than once between releases. On my first deploy I had a page that showed stale data for fifteen minutes and I couldn’t figure out why. Nothing in my code said “cache this.” The fetch did it for me.<\/p>\n The fix was learning the opt-out knobs and being explicit everywhere data changes often:<\/p>\n I don’t love that the safe default for a lot of apps is “turn the magic off until you understand it.” If your app is mostly dynamic, you’ll be sprinkling The reflex when something breaks is to slap The pattern that kept my bundles small was pushing the client boundary as far down the tree as possible. A page stays a Server Component. Only the genuinely interactive leaf, the button with the click handler, the input with local state, gets marked:<\/p>\n The server page imports Don’t migrate the whole app in one shot unless something forces you to. The pages\/about.tsx<\/code> becomes app\/about\/page.tsx<\/code>. The part that takes a day to click is that most of your components now run on the server by default and never ship to the browser. That’s the whole game. Everything in the app\/<\/code> directory is a Server Component unless you opt out.<\/p>\ngetServerSideProps<\/code> into some new equivalent. I was deleting it, because the component itself can now do the fetch. The React Server Components reference<\/a> is the clearest explanation of why this works, and it’s worth twenty minutes before you touch any code.<\/p>\nData fetching: deleting getServerSideProps<\/h2>\n
\/\/ pages\/dashboard.tsx (Pages Router)\nexport async function getServerSideProps(context) {\n const res = await fetch(`https:\/\/api.internal\/user\/${context.query.id}`);\n const user = await res.json();\n return { props: { user } };\n}\n\nexport default function Dashboard({ user }) {\n return <h1>Welcome back, {user.name}<\/h1>;\n}\n<\/code><\/pre>\n\/\/ app\/dashboard\/[id]\/page.tsx (App Router)\nexport default async function Dashboard({ params }) {\n const res = await fetch(`https:\/\/api.internal\/user\/${params.id}`);\n const user = await res.json();\n return <h1>Welcome back, {user.name}<\/h1>;\n}\n<\/code><\/pre>\nasync<\/code>. You await<\/code> right in the render. The user<\/code> object never gets serialized into a props blob for the client, because this component runs on the server and only its rendered output crosses the wire. On the dashboard I migrated, that alone cut the initial payload by a noticeable chunk, mostly because a bunch of data that used to ride along in props simply stopped shipping.<\/p>\nLayouts stopped being a hack<\/h2>\n
getLayout<\/code> pattern bolted onto the page component, and it always felt like a workaround because it was one:<\/p>\n\/\/ pages\/_app.tsx (Pages Router)\nexport default function App({ Component, pageProps }) {\n const getLayout = Component.getLayout || ((page) => page);\n return getLayout(<Component {...pageProps} \/>);\n}\n\n\/\/ then every page had to export its own getLayout...\nDashboard.getLayout = (page) => <SidebarLayout>{page}<\/SidebarLayout>;\n<\/code><\/pre>\nlayout.tsx<\/code> wraps every route in its folder, and it doesn’t re-render when you navigate between child routes. That last part is the bit I actually cared about:<\/p>\n\/\/ app\/dashboard\/layout.tsx (App Router)\nexport default function DashboardLayout({ children }) {\n return (\n <div className="flex">\n <Sidebar \/>\n <main>{children}<\/main>\n <\/div>\n );\n}\n<\/code><\/pre>\n\/dashboard\/reports<\/code> to \/dashboard\/settings<\/code> and the Sidebar<\/code> stays mounted. No flicker, no re-fetch, and my scroll position stays put. On the Pages Router I’d been faking this with a global state hack that stashed the sidebar in a context provider, and it broke every few months whenever someone added a new top-level route and forgot to wire it up. Here it just works because the router understands the nesting. The official App Router docs<\/a> lay out the file conventions if you want the full set.<\/p>\nThe caching that bit me<\/h2>\n
\/\/ force a fresh fetch every request\nconst res = await fetch(url, { cache: 'no-store' });\n\n\/\/ or revalidate on a timer\nconst res = await fetch(url, { next: { revalidate: 60 } });\n<\/code><\/pre>\ncache: 'no-store'<\/code> around for a while before the model clicks. The rules also shifted between Next 14 and 15, so half the Stack Overflow answers you’ll find describe behavior that no longer applies. Check the version on any advice before you trust it. Budget real time for this. The migration guide covers the caching behavior, and I’d read the official Pages-to-App migration guide<\/a> end to end before you ship, not after you get paged about stale data.<\/p>\nWhere ‘use client’ actually goes<\/h2>\n
'use client'<\/code> at the top of the file and move on. Resist it. Every time you do that, you’re pulling that component and its imports back into the browser bundle, which is the exact thing you migrated to avoid.<\/p>\n\/\/ app\/dashboard\/like-button.tsx\n'use client';\nimport { useState } from 'react';\n\nexport default function LikeButton() {\n const [liked, setLiked] = useState(false);\n return <button onClick={() => setLiked(!liked)}>{liked ? 'Liked' : 'Like'}<\/button>;\n}\n<\/code><\/pre>\n<LikeButton \/><\/code> and renders it, but stays on the server itself. I got this wrong for the first two days and wondered why my bundle barely shrank. The boundary is a tool, not a default.<\/p>\nWhat I’d do this week<\/h2>\n
app\/<\/code> and pages\/<\/code> directories run side by side, which is the single best thing about this migration. Pick one leaf route with real data fetching, move it to a page.tsx<\/code>, delete its getServerSideProps<\/code>, and watch the network tab. Once you’ve felt the payload drop and the layout stop flickering, you’ll know whether the rest is worth your weekend.<\/p>\n