Szybka odpowiedź: jak bezpiecznie przenieść projekt z Pages Router na App Router?
- Migruj stopniowo, bo
pages/iapp/mogą działać obok siebie. - Zacznij od dodania
app/layout.tsx, zachowując_appi_documentdla 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.
getStaticPropszastępujesz Server Componentem,next/headeksportemmetadata, anext/routerimportem znext/navigation.- Nie usuwaj
pages/, dopóki wszystkie trasy nie działają wapp/.
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.
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
Faza 1: migracja _app.tsx i _document.tsx do layout.tsx
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
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.
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 Router | App Router |
|---|---|
getStaticProps | Server Component z danymi możliwymi do prerenderowania |
getServerSideProps | async Server Component + export const dynamic = 'force-dynamic' |
getStaticPaths | generateStaticParams |
revalidate w wyniku getStaticProps | export const revalidate = N |
notFound: true | notFound() 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:
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:
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
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
Lista kontrolna migracji Pages Router do App Router
- Dodaj
app/layout.tsx; zachowaj_app.tsxi_document.tsx, dopóki obsługują strony wpages/. - Przenieś metadane z
next/headdo eksportumetadatalub funkcjigenerateMetadata. - Przenieś
getStaticPropsdo Server Component i dobierz cache:revalidatebez Cache Components albouse cacheicacheLifez Cache Components. - Przenieś
getServerSidePropsdo Server Component: bez Cache Components możesz użyćdynamic = 'force-dynamic', a z Cache Components umieść dane żądania podSuspense. - Zastąp
getStaticPathsfunkcjągenerateStaticParams. - Opcjonalnie przenieś
pages/api/*.tsdoapp/api/*/route.ts, zachowując kontrakt endpointów i walidację. - Zamień importy z
next/routernanext/navigation. - Zastąp odczyt
router.queryhookamiuseParams()iuseSearchParams(). - Wyznacz granice
'use client'przy każdej migrowanej stronie; uwzględnijSuspensedlauseSearchParams. - Zamień
getLayoutna zagnieżdżonylayout.tsx. - Porównaj metadane, linki kanoniczne, robots, statusy HTTP i przekierowania oraz sprawdź produkcyjny build i najważniejsze przepływy użytkownika.


