Przejdź do treści

Pages Router do App Router: migracja w Next.js

Maciej Sala

Founder StriveLab

7 min czytaniaAktualizacja

Szybka odpowiedź: jak bezpiecznie przenieść projekt z Pages Router na App Router?

  • Migruj stopniowo, bo pages/ i app/ mogą działać obok siebie.
  • Zacznij od dodania app/layout.tsx, zachowując _app i _document dla istniejących stron. Granice Client Components ustalaj przy każdej przenoszonej stronie; API możesz migrować osobno.
  • Każdą ścieżkę testuj i wdrażaj osobno.
  • getStaticProps zastępujesz Server Componentem, next/head eksportem metadata, a next/router importem z next/navigation.
  • Nie usuwaj pages/, dopóki wszystkie trasy nie działają w app/.

to główny kierunek rozwoju Next.js — pod app/ projektowane są przede wszystkim , streaming, Server Actions, Parallel Routes i PPR. nadal działa i jest wspierany, więc migracja nie musi być natychmiastowa ani obowiązkowa. Może zmniejszyć paczkę JS i poprawić TTFB, ale zależy to od granic komponentów, pobierania danych oraz cache, więc wymaga pomiarów. Zyskujesz też zagnieżdżone layouty, Server Actions do formularzy oraz obsługę ładowania i błędów na poziomie segmentów tras. Jeśli chcesz najpierw zrozumieć, dlaczego model server-first zmienia architekturę, zacznij od artykułu o granicy serwer–klient w Next.js.

Migracja Pages Router do App Router: oba routery mogą współistnieć

Next.js pozwala używać pages/ i app/ w tym samym projekcie i to najlepsza wiadomość przy migracji. Przenosisz jedną ścieżkę, testujesz, wdrażasz i dopiero wtedy bierzesz następną. Pamiętaj, by nie migrować wszystkiego naraz.

Code
next-app/
├── app/              ← Nowe strony (App Router)
│   ├── layout.tsx
│   ├── page.tsx      ← Strona główna (już przeniesiona)
│   └── blog/
│       └── page.tsx  ← Blog (już przeniesiony)
├── pages/            ← Stare strony (Pages Router)
│   ├── products/
│   │   └── [id].tsx  ← Jeszcze nieprzeniesione
│   └── dashboard.tsx ← Jeszcze nieprzeniesione

Katalogi app/ i pages/ mogą współistnieć, ale nie powinny definiować tej samej ścieżki. App Router ma priorytet, a duplikaty będą powodować błąd builda, więc przenieś trasę i usuń jej odpowiednik z pages/.

Pamiętaj, że istnieje jeden efekt uboczny: przejście linkiem między stroną z pages/ a stroną z app/ to twarde przeładowanie (hard navigation), a next/link nie pobiera stron z wyprzedzeniem (prefetch) przez granicę routerów. Dopóki będzie trwała migracja, część nawigacji będzie wolniejsza niż w czysto klienckich przejściach. Jest to jednak normalne i znika, gdy wszystkie trasy trafią do app/. Uwzględnij też reset stanu React przy pełnym przeładowaniu, np. koszyka przechowywanego wyłącznie w Context, a potem oceń wpływ tych przejść na użytkowników podczas migracji.

Plan migracji Pages Router do App Router krok po kroku

Diagram
Migracja strona po stronie: każda trasa przechodzi ten sam cykl, a pages/ znika dopiero na końcu.

Faza 1: migracja _app.tsx i _document.tsx do layout.tsx

Code
// PRZED: pages/_app.tsx
import type { AppProps } from 'next/app'
import { ThemeProvider } from '@/components/theme-provider'
import '@/styles/globals.css'
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider>
      <Header />
      <Component {...pageProps} />
      <Footer />
    </ThemeProvider>
  )
}
Code
// PRZED: pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document'
 
export default function Document() {
  return (
    <Html lang="pl">
      <Head>
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
Code
// PO: app/layout.tsx — łączy _app.tsx i _document.tsx
// ThemeProvider opiera się na React Context, więc jego plik musi mieć
// dyrektywę 'use client' na górze — sam layout zostaje Server Componentem.
import { ThemeProvider } from '@/components/theme-provider'
import { Header } from '@/components/header'
import { Footer } from '@/components/footer'
import '@/styles/globals.css'
 
export const metadata = {
  title: { default: 'Acme', template: '%s — Acme' },
  description: 'Tworzenie stron w Next.js',
  icons: { icon: '/favicon.ico' },
}
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="pl">
      <body>
        <ThemeProvider>
          <Header />
          <main>{children}</main>
          <Footer />
        </ThemeProvider>
      </body>
    </html>
  )
}

W App Routerze <Head> z next/head jest zastępowany przez metadata, więc zamiast importować next/head w app/, należy użyć eksportu metadata albo funkcji generateMetadata.

Na tym etapie łatwo zapomnieć o dwóch kwestiach. Po pierwsze, app/layout.tsx musi samodzielnie renderować znaczniki <html> i <body>, ponieważ Next.js nie dodaje ich automatycznie, w przeciwieństwie do _document.tsx. Po drugie, nie należy od razu usuwać _app.tsx ani _document.tsx; dopóki w pages/ istnieją jakiekolwiek strony, te pliki nadal je obsługują, a style i logika z głównego layoutu nie mają zastosowania do tras z pages/. Można je usunąć po przeniesieniu wszystkich stron; pozostawione pages/api nie korzysta z tych plików.

Jeśli _app.tsx zawiera Context Providery (np. dla motywu, koszyka czy stanu autoryzacji), pamiętaj, że w app/ muszą one znaleźć się w osobnym komponencie z dyrektywą 'use client', ponieważ sam root layout pozostaje Server Componentem.

Faza 2: migracja statycznych stron do App Routera

Code
// PRZED: pages/about.tsx
import Head from 'next/head'
 
export default function About() {
  return (
    <>
      <Head>
        <title>O nas — Acme</title>
      </Head>
      <h1>O nas</h1>
      <p>Acme — agencja software'owa</p>
    </>
  )
}
Code
// PO: app/about/page.tsx
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'O nas',
  description: "Acme — agencja software'owa, Next.js, React.",
}
 
export default function AboutPage() {
  return (
    <>
      <h1>O nas</h1>
      <p>Acme — agencja software'owa</p>
    </>
  )
}

Zmiany: next/head → export const metadata, nazwa pliku about.tsx → about/page.tsx.

Faza 3: pobieranie danych z getServerSideProps i getStaticProps do Server Components

Poniższy przykład i tabela dotyczą modelu bez Cache Components przy wyłączonym cacheComponents. Pozwala to oddzielić migrację routera od zmiany modelu cache. Gdy Cache Components są włączone, nie stosuj eksportów dynamic i revalidate, lecz użyj "use cache" z cacheLife dla danych cache'owanych oraz <Suspense> dla danych pobieranych w czasie żądania. Zobacz dokumentację konfiguracji tras.

Code
// PRZED: pages/blog/[slug].tsx
import { GetStaticProps, GetStaticPaths } from 'next'
 
export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await getAllPosts()
  return {
    paths: posts.map((post) => ({ params: { slug: post.slug } })),
    fallback: 'blocking',
  }
}
 
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const post = await getPost(params?.slug as string)
  if (!post) return { notFound: true }
  return { props: { post }, revalidate: 3600 }
}
 
export default function BlogPost({ post }: { post: Post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
}
Code
// PO: app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'
 
export const revalidate = 3600 // ISR — odpowiednik revalidate w getStaticProps
 
export async function generateStaticParams() {
  const posts = await getAllPosts()
  return posts.map((post) => ({ slug: post.slug }))
}
 
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)
  if (!post) return {}
  return { title: post.title, description: post.excerpt }
}
 
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  if (!post) notFound()
 
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
}

Funkcje getAllPosts, getPost oraz typ Post pochodzą z warstwy danych aplikacji, dlatego w przykładzie pominięto ich importy i implementację. ISR zakłada, że getPost nie wymusza renderowania na każde żądanie, na przykład przez cache: 'no-store' lub odczyt cookies. HTML w post.content musi być wcześniej oczyszczony, jeśli pochodzi z niezaufanego źródła, ponieważ dangerouslySetInnerHTML niczego nie oczyszcza.

Mapowanie bez Cache Components:

Pages RouterApp Router
getStaticPropsServer Component z danymi możliwymi do prerenderowania
getServerSidePropsasync Server Component + export const dynamic = 'force-dynamic'
getStaticPathsgenerateStaticParams
revalidate w wyniku getStaticPropsexport const revalidate = N
notFound: truenotFound() z next/navigation
fallback: 'blocking'dynamicParams = true pozwala obsłużyć nowe ścieżki; nie odwzorowuje dokładnie blokowania odpowiedzi

Faza 4: migracja API Routes do Route Handlers

w App Routerze zastępują API Routes z pages/api/, ale ich migracja nie jest wymagana do korzystania z App Routera. Możesz pozostawić pages/api po przeniesieniu wszystkich stron. Przy okazji migracji warto rozważyć, czy dany endpoint w ogóle powinien zostać Route Handlerem, czy lepiej przepisać go na Server Action. Tutaj może pomóc porównanie Server Actions i Route Handlers:

Code
// PRZED: pages/api/contact.ts
import type { NextApiRequest, NextApiResponse } from 'next'
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }
 
  const { name, email, message } = req.body
  // ... logika
  res.status(200).json({ success: true })
}
Code
// PO: app/api/contact/route.ts
import { NextResponse } from 'next/server'
 
export async function POST(request: Request) {
  const { name, email, message } = await request.json()
  // ... logika
  return NextResponse.json({ success: true })
}
 
// Opcjonalnie — jawny handler dla nieobsługiwanych metod nie jest potrzebny
// Next.js zwraca 405 dla nieobsługiwanych metod; OPTIONS generuje automatycznie

Samo request.json() jedynie parsuje treść JSON, więc przeniesienie endpointu musi zachować walidację danych oraz kontrolę dostępu, a niepoprawny JSON warto obsłużyć jako błąd klienta. Powyższy kod pokazuje wyłącznie zmianę samej obsługi endpointu.

Faza 5: Client Components i dyrektywa 'use client'

Ten krok wykonuj przy każdej przenoszonej stronie, a nie dopiero na końcu migracji. W Pages Router interfejs jest hydratowany w przeglądarce, choć jego HTML może powstać na serwerze, natomiast w App Router komponenty są domyślnie serwerowe. Hooki stanu i efektów oraz obsługa zdarzeń wymagają granicy 'use client', przy czym dyrektywę dodajesz w pliku wejściowym tej części interfejsu, a nie w każdym importowanym przez niego komponencie:

Code
// Ten komponent musi mieć 'use client' w App Router
'use client'
 
import { useState } from 'react'
 
export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Zwykle warto zachować layout.tsx i page.tsx jako Server Components, a interaktywność wydzielić. Pliki te mogą jednak być Client Components — to nie zakaz frameworka. Pamiętaj wtedy o ograniczeniach, m.in. braku eksportu metadata i generateMetadata. Bezpiecznym pierwszym krokiem bywa przeniesienie dotychczasowego interfejsu do Client Component, któremu serwerowa strona przekazuje dane, a dopiero później ograniczanie części klienckiej.

Typowe pułapki przy migracji na App Router

useRouter w App Router: inna paczka i inne API

Code
// Pages Router
import { useRouter } from 'next/router' // next/router
 
// App Router
import { useRouter } from 'next/navigation' // next/navigation

API jest inne: router.query nie istnieje w App Router — w Client Components użyj useParams() i useSearchParams(). Przy statycznym renderowaniu komponent z useSearchParams() otocz <Suspense>; bez tej granicy produkcyjny build może się nie udać, choć w trybie deweloperskim wszystko działa. W serwerowej stronie korzystaj z asynchronicznych propsów params i searchParams. Zobacz dokumentację useSearchParams.

Metadata API zamiast next/head

next/head nie działa w app/. Użyj export const metadata (statyczne) lub export async function generateMetadata (dynamiczne).

i18n w App Router: konfiguracja biblioteki i routingu językowego

next-i18next v16 obsługuje App Router i projekty mieszane: udostępnia m.in. getT() dla Server Components, useT() dla Client Components i createProxy() do routingu językowego. Możesz zachować bibliotekę po dostosowaniu konfiguracji i importów; next-intl jest alternatywą. Zaplanuj segmenty [locale], adresy i metadane przed przeniesieniem pierwszej wielojęzycznej trasy — starej konfiguracji nie kopiujesz 1:1. Routing wielojęzycznej strony razem z jej stroną SEO (hreflang, link kanoniczny) opisuję w artykule hreflang i link kanoniczny w Next.js.

Zagnieżdżone layouty zamiast wzorca getLayout

Code
// PRZED: Pages Router — wzorzec getLayout
ProductPage.getLayout = (page) => <DashboardLayout>{page}</DashboardLayout>
 
// PO: App Router — zagnieżdżony layout.tsx
// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  return <DashboardShell>{children}</DashboardShell>
}

Lista kontrolna migracji Pages Router do App Router

  1. Dodaj app/layout.tsx; zachowaj _app.tsx i _document.tsx, dopóki obsługują strony w pages/.
  2. Przenieś metadane z next/head do eksportu metadata lub funkcji generateMetadata.
  3. Przenieś getStaticProps do Server Component i dobierz cache: revalidate bez Cache Components albo use cache i cacheLife z Cache Components.
  4. Przenieś getServerSideProps do Server Component: bez Cache Components możesz użyć dynamic = 'force-dynamic', a z Cache Components umieść dane żądania pod Suspense.
  5. Zastąp getStaticPaths funkcją generateStaticParams.
  6. Opcjonalnie przenieś pages/api/*.ts do app/api/*/route.ts, zachowując kontrakt endpointów i walidację.
  7. Zamień importy z next/router na next/navigation.
  8. Zastąp odczyt router.query hookami useParams() i useSearchParams().
  9. Wyznacz granice 'use client' przy każdej migrowanej stronie; uwzględnij Suspense dla useSearchParams.
  10. Zamień getLayout na zagnieżdżony layout.tsx.
  11. Porównaj metadane, linki kanoniczne, robots, statusy HTTP i przekierowania oraz sprawdź produkcyjny build i najważniejsze przepływy użytkownika.
Elastyczne i wydajne narzędzia dla biznesu, które dotrzymają kroku Twojemu rozwojowi.
Next.js

Często zadawane pytania

Czy muszę migrować cały projekt naraz?

Nie. Pages Router i App Router współistnieją w jednym projekcie i to jest właśnie fundament inkrementalnej migracji. Przenosisz stronę po stronie, testujesz i wdrażasz, zaczynając od najprostszych stron statycznych. Ważne ograniczenie: app/ i pages/ nie mogą definiować tej samej ścieżki, bo App Router ma priorytet, a duplikat będzie psuł builda.

Jak przenieść pobieranie danych z Pages na App Router?

Pobieranie danych przenosisz do Server Components, ale samo async nie gwarantuje SSG. Bez Cache Components możesz użyć dynamic = 'force-dynamic' dla renderowania na żądanie i export const revalidate = N dla ISR. Przy Cache Components stosujesz use cache i cacheLife oraz Suspense dla danych czasu żądania. getStaticPaths zastępujesz funkcją generateStaticParams, a notFound: true — wywołaniem notFound() z next/navigation.

Czy migracja wpływa na SEO?

Może wpływać. Zachowaj URL-e i treść, ale porównaj też metadane, linki kanoniczne, robots, statusy HTTP i przekierowania. Metadata API pozwala odtworzyć tagi, lecz nie przenosi ich automatycznie. Sprawdź odpowiedzi przed wdrożeniem, a po migracji monitoruj indeksację w Search Console.

Jak długo będzie wspierany Pages Router?

Next.js oficjalnie utrzymuje Pages Router jako stabilny i wspierany, aktualnie nie ma publicznej daty końca wsparcia. Nowe funkcje (Server Components, streaming, Server Actions, Parallel Routes, PPR) są jednak rozwijane głównie pod app/. Termin migracji powinien wynikać z potrzeb projektu.

Co z next/router i router.query po migracji?

W App Router importujesz useRouter z next/navigation zamiast next/router, a API jest inne i router.query nie istnieje. Zamiast niego używasz useParams() do parametrów ścieżki i useSearchParams() do parametrów zapytania. To jedna z najczęstszych pułapek przy przenoszeniu interaktywnych komponentów.

Co zrobić z i18n opartym o next-i18next?

next-i18next v16 obsługuje Pages Router, App Router oraz projekty mieszane. Możesz zachować bibliotekę, dostosowując konfigurację i importy; next-intl jest alternatywą, nie wymogiem. Zaplanuj routing językowy i metadane SEO przed przeniesieniem pierwszej wielojęzycznej trasy.

Czy da się zautomatyzować część migracji do App Routera?

Częściowo. Next.js dostarcza oficjalny pakiet @next/codemod z transformacjami do najbardziej mechanicznych zmian. Najważniejszą jest next-async-request-api, który dodaje await do asynchronicznych params i searchParams (zmiana z Next.js 15). Uruchamiasz ją przez npx @next/codemod@latest next-async-request-api . Codemody nie przepiszą jednak logiki pobierania danych (getStaticProps na Server Component) ani routingu — to wciąż praca ręczna. Traktuj je jako akcelerator nudnych zamian, nie zamiennik strategii migracji. Przejrzyj wynik oraz miejsca oznaczone przez codemod jako wymagające ręcznej poprawy.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Next.js i React

Czytaj dalej

Zobacz więcej wpisów
App Router czy Pages Router w Next.js: co wybrać?

Next.js 13 wprowadził App Router , czyli nowy sposób budowania aplikacji oparty na React Server Components . Ale Pages Router nigdzie nie zniknął. Dwa routery, dwa podejścia, jedna decyzja do podjęcia na starcie projektu.

Maciej Sala

Maciej Sala

Founder StriveLab

Server i Client Components w Next.js: gdzie przebiega granica serwer–klient

Komponent działa lokalnie, ale po wdrożeniu na produkcję pojawia się niezgodność hydratacji ang. hydration mismatch , a prosta strona produktu pobiera kilkaset kilobajtów JavaScriptu. Zamiast natychmiast wyłączać SSR czy otaczać kod memoizacją, warto cofnąć się o krok. Problem rzadko leży w braku optymalizacji — częściej w braku decyzji, która część interfejsu realnie wymaga przeglądarki. React Server Components przesunęły granicę między serwerem a klientem. W App Routerze najpierw decydujemy, gdzie wykonać pracę, a dopiero potem dobieramy hooki i biblioteki.

Maciej Sala

Maciej Sala

Founder StriveLab

Astro czy Next.js w 2026: porównanie frameworków

Astro czy Next.js? Wybór frameworka musi być dokładnie przemyślany, zanim pojawi się pierwszy commit. Jeśli stoisz przed takim właśnie wyborem, w tym artykule staram się wykazać, w jakich obszarach najlepiej sprawdza się Astro , a w jakich będzie dominował Next.js .

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G