Next.js versiyalarini yangilash: codemod, 15 va 16 o'zgarishlari, Pages Router merosi

Qisqacha: Next.js har yili katta versiya chiqaradi va ularda "buzuvchi" o'zgarishlar bo'ladi. Ularni qo'lda tuzatish o'rniga codemod ishlatiladi — kodni avtomatik qayta yozadigan dastur: npx @next/codemod@16.4.0 <transform> .. 14 → 15 da params, cookies(), headers() Promise bo'ldi va fetch sukut bo'yicha keshlanmay qoldi. 15 → 16 da middleware.ts → proxy.ts, Turbopack sukut, next lint olib tashlandi, Node 20.9+ talab qilinadi. Eski loyihalarning ko'pi esa Pages Router da (pages/, getStaticProps, getServerSideProps, _app, _document) — uni o'qiy olish ishga kirgandagi birinchi vazifalardan biri.

Bu darsda

• Codemod nima ekanini va uni qanday xavfsiz ishlatishni bilasiz.
• 14 → 15 va 15 → 16 ning asosiy o'zgarishlarini sanab, eski koddagi belgilarini taniysiz.
• Codemod natijasini (hisobot emas, faylning o'zini) tekshirishni o'rganasiz — biz topgan "0 ok" tuzog'i bilan.
• Pages Router faylini o'qiysiz: getStaticProps, getServerSideProps, _app, _document — App Router'dagi juftlari bilan.
• Aralash loyihada (app/ + pages/) navigatsiya hooklari nega null qaytarishi mumkinligini bilasiz.

Oldin bilishingiz kerak: Semver va versiya diapazonlari, Fayl-asosli routing, proxy.ts, Cache Components I, Next.js nima.

1. Nega bu kerak?

Aziz birinchi ishiga kirdi. Jamoa loyihasi 2022-yilda boshlangan, package.json da "next": "13.4.0". Papkalarda app/ yo'q, o'rnida pages/. Fayllarda kursda ko'rmagan funksiyalar: getServerSideProps. Birinchi vazifa: "loyihani Next 16 ga ko'tar".

Bu odatiy holat. Next.js nima darsida Pages Router'ni "eski yo'l" deb tilga olgandik. Lekin eski degani yo'q degani emas: ishlab turgan minglab loyihalar shu yo'lda yozilgan va hali ham Next 16 da ishlaydi.

Ikki ko'nikma kerak: versiyani xavfsiz ko'tarish va eski kodni o'qish. Ikkinchisisiz birinchisi ham bo'lmaydi.

O'xshatish: eski uyni ta'mirlash. Avval uyning chizmasini o'qiysiz (qayerda quvur, qayerda sim). Keyin ishni bosqichma-bosqich qilasiz — devorni birdan buzmaysiz. Codemod — elektr kabelini topadigan asbob: ko'p ishni tezlashtiradi, lekin oxirgi qarorni usta qiladi.

2. Versiya ko'tarish tartibi

2.1 Semver va Next

Semver darsidan: 16.4.0 — katta.kichik.tuzatish. Kichik va tuzatish versiyalar orasida (16.3 → 16.4) buzuvchi o'zgarish bo'lmasligi kerak. Katta versiyada (15 → 16) — bo'ladi. Next har katta versiya uchun rasmiy yangilash qo'llanmasi yozadi (upgrading/version-15, version-16).

Qoida: katta versiyalarni birma-bir ko'taring. 13 dan 16 ga sakramang: 13 → 14 → 15 → 16, har qadamda build, testlar, commit.

2.2 Codemod nima

Codemod (code modification — kod o'zgartirish) — kodni avtomatik qayta yozadigan dastur. U faylni matn sifatida emas, sintaksis daraxti (AST — kodning tuzilma ko'rinishi, ESLint ham shu bilan ishlaydi) sifatida o'qiydi. Shuning uchun u params so'zini izoh ichida emas, faqat kerakli joyda o'zgartiradi.

Next'ning codemod'lari @next/codemod paketida. Har biri — bitta transform (o'zgartirish turi):

npx @next/codemod@16.4.0 <transform> <papka>

Xavfsizlik qoidalari: avval git toza bo'lsin (codemod o'zi tekshiradi va ogohlantiradi), keyin ishga tushiring, keyin git diff bilan har o'zgarishni ko'ring. --dry — faqat ko'rsatadi, --print — natijani ekranga chiqaradi.

Rasmiy qo'llanma yana upgrade buyrug'ini taklif qiladi: npx @next/codemod upgrade latest — paketlarni ko'taradi va kerakli transform'larni o'zi tanlaydi. Kanon transform'larni alohida, nazorat ostida ishlatdi.

3. 14 → 15: Promise va kesh

3.1 Async Request API'lar

Next 15 dagi eng katta o'zgarish. Avval sinxron bo'lgan narsalar Promise bo'ldi: params, searchParams, cookies(), headers(), draftMode(). Sababi — Next sahifaning qaysi qismi so'rovga bog'liqligini aniq bilishi kerak: await qilingan joy — "shu yerdan boshlab dinamik" degan belgi (Rendering strategiyalari).

Fayl-asosli routing darsida params ni await siz o'qish jim undefined berishini ko'rgansiz. Eski kodda aynan shunday yozilgan.

3.2 Kesh sukutlari teskari bo'ldi

Next 14 da "nega yangi ma'lumot ko'rinmayapti?" eng ko'p savol edi — hamma narsa jim keshlanardi. 15 "aniq so'ramaguncha keshlama" yo'lini tanladi, 16 esa Cache Components bilan uni "use cache" direktivasiga aylantirdi (Cache Components I). Eski loyihani ko'targanda eng xavfli joy shu: kod o'zgarmaydi, lekin xulq o'zgaradi. Avval keshdan tez berilgan sahifa endi har so'rovda tashqi API'ga boradi.

3.3 React 19

Next 15 App Router uchun React 19 ni talab qiladi. React 19 darslarida o'rganganingiz — ref prop, use(), Actions — shu versiyadan. Eski loyihada forwardRef va useFormState ni ko'rasiz; ular React 19 da ham ishlaydi, lekin yangisi qisqaroq.

4. 15 → 16: kanon tajribasi

4.1 O'zgarishlar ro'yxati

Rasmiy version-16 qo'llanmasidan asosiylari:

portfolio skeletida bularning ko'pi allaqachon to'g'ri: package.json dagi lint skripti eslint --max-warnings=0 ni to'g'ridan chaqiradi (Loyiha yaratish), @modal/default.tsx bor (Parallel routes).

4.2 Biz ishga tushirdik: ikki codemod

Kanon Next 15 uslubidagi kichik loyihada @next/codemod@16.4.0 ni sinadi. Biz tajribani qayta qildik. Boshlang'ich ikki fayl — Next 15 ning odatiy kodi:

// middleware.ts
import { NextResponse, type NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  return NextResponse.next();
}

export const config = { matcher: ["/blog/:path*"] };

// app/blog/[slug]/page.tsx — Next 14 uslubi
import { cookies } from "next/headers";

export default function Post({ params }: { params: { slug: string } }) {
  const tema = cookies().get("tema");
  return <h1>{params.slug} {tema?.value}</h1>;
}

Birinchi transform:

npx @next/codemod@16.4.0 middleware-to-proxy . --force

Processing 2 files... 
All done. 
Results: 
0 errors
1 unmodified
1 skipped
0 ok
Time elapsed: 16.205seconds 

Hisobot "0 ok, 1 skipped" deydi — ya'ni hech narsa o'zgarmaganga o'xshaydi. Lekin git status:

 M app/blog/[slug]/page.tsx
 D middleware.ts
?? proxy.ts

(page.tsx — ikkinchi transform'dan, pastda.) middleware.ts o'chirildi, proxy.ts paydo bo'ldi, ichida export function proxy. Transform faylni qayta nomlab, funksiyani o'zgartirdi — jscodeshift hisoboti esa buni "skipped" deb sanadi. Kanon ham, biz ham shuni ko'rdik. Saboq: hisobotga emas, natijaga qarang — git status va git diff.

Ikkinchi transform:

npx @next/codemod@16.4.0 next-async-request-api . --force

Hisobotda 1 ok. Natija:

import { cookies } from "next/headers";

export default async function Post(props: { params: Promise<{ slug: string }> }) {
  const params = await props.params;
  const tema = (await cookies()).get("tema");
  return <h1>{params.slug} {tema?.value}</h1>;
}

Uch o'zgarish: komponent async bo'ldi; params turi Promise<…> va await props.params; cookies() await bilan o'raldi. Kod qatori 70 belgidan uzun — codemod chiqishi aynan. Prettier uni keyin formatlaydi. Codemod PageProps<"/blog/[slug]"> kabi Next 16 turini qo'ymadi — buni o'zingiz qilasiz (Fayl-asosli routing).

4.3 Jonli: codemod g'oyasi

Haqiqiy codemod AST bilan ishlaydi. Lekin uning vazifasini kichik matn modeli bilan ko'rish mumkin — va nega matn bilan qilish xavfli ekanini ham:

function renameMiddleware(source) {
  return source.replace(
    /export function middleware\(/g,
    "export function proxy(",
  );
}

const before = [
  "export function middleware(request) {",
  "  // middleware — eski nom, Next 15",
  "  return NextResponse.next();",
  "}",
].join("\n");

console.log(renameMiddleware(before));

Konsolda:

export function proxy(request) {
  // middleware — eski nom, Next 15
  return NextResponse.next();
}

Model ishladi: izohdagi middleware so'ziga tegmadi, chunki naqsh aniq (export function middleware(). Lekin export async function middleware( yoki const middleware = …; export { middleware } yozilgan bo'lsa — model ko'rmaydi. Haqiqiy codemod sintaksis daraxtida "eksport qilingan middleware nomli funksiya"ni qanday yozilganidan qat'i nazar topadi. Shuning uchun katta o'zgarishlarda regex emas, codemod.

Tekshirib ko'ring: Codemod hisobotida "0 errors, 0 ok". Ish bajarilmagan deb xulosa qilsa bo'ladimi?

5. Pages Router: o'qish uchun

5.1 Tuzilma

Pages Router'da marshrutlar pages/ papkasida, va har fayl — sahifa (App Router'da esa papka + page.tsx):

Eng katta farq: Pages Router'da Server Component yo'q. Har sahifa komponenti — client komponent (serverda ham chiziladi, keyin hydration). Ma'lumot esa sahifadan tashqarida, maxsus funksiyada olinadi.

5.2 getStaticProps — build vaqtida

// pages/blog/[slug].tsx
import type { GetStaticPaths, GetStaticProps } from "next";

type Props = { title: string };

export const getStaticPaths: GetStaticPaths = async () => ({
  paths: [{ params: { slug: "salom" } }],
  fallback: "blocking",
});

export const getStaticProps: GetStaticProps<Props> = async ({
  params,
}) => ({
  props: { title: `Post: ${String(params?.slug)}` },
  revalidate: 60,
});

export default function Post({ title }: Props) {
  return <h1>{title}</h1>;
}

Mexanizmni oddiy JS bilan ko'ring — Next build vaqtida aynan shunday qiladi: funksiyani chaqiradi, natijadagi props ni komponentga beradi:

async function getStaticProps({ params }) {
  return {
    props: { title: `Post: ${params.slug}` },
    revalidate: 60,
  };
}

function Post({ title }) {
  return `<h1>${title}</h1>`;
}

const result = await getStaticProps({ params: { slug: "salom" } });
console.log(Post(result.props));
console.log(`${result.revalidate} soniyadan keyin qayta yaratiladi`);

Konsolda:

<h1>Post: salom</h1>
60 soniyadan keyin qayta yaratiladi

Bu — ISR (Incremental Static Regeneration): sahifa statik, lekin 60 soniyadan keyin birinchi so'rovda fonda yangilanadi. App Router'da bu g'oya cacheLife ga ko'chdi.

5.3 getServerSideProps — har so'rovda

import type { GetServerSideProps } from "next";

export const getServerSideProps: GetServerSideProps = async ({
  req,
}) => {
  const tema = req.cookies.tema ?? "yorug";
  return { props: { tema } };
};

Har so'rovda serverda bajariladi — sahifa doim dinamik (App Router'dagi ƒ). req — Node so'rovi, cookie to'g'ridan o'qiladi. App Router juftligi: Server Component ichida await cookies(). Ikkala funksiyadan return { notFound: true } yoki { redirect: { destination, permanent } } qaytarish mumkin — App Router'dagi notFound() va redirect() ning ajdodlari.

5.4 _app va _document

// pages/_app.tsx — har sahifani o'raydi
import type { AppProps } from "next/app";
import "../styles/globals.css";

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

_app — hamma sahifa uchun umumiy o'ram: global CSS, provider'lar, umumiy layout. Component — joriy sahifa, pageProps — getStaticProps/getServerSideProps qaytargan props. Farq: _app client'da yashaydi va har o'tishda sahifa almashadi, lekin ichma-ich layout yo'q — App Router'dagi papka bo'yicha layout'lar (Layout va template) aynan shu kamchilikni yopdi.

_document — faqat serverda bir marta chiziladigan HTML qobig'i (<Html>, <Head>, <Main />, <NextScript />). Unda lang, shrift havolalari bo'ladi. App Router'da u root layout'ning <html>/<body> qismiga aylandi.

5.5 Biz topdik: aralash loyiha va null

Next 16 da app/ va pages/ bitta loyihada yonma-yon ishlaydi — bosqichma-bosqich ko'chish shunday qilinadi. Kanon buni sinadi: portfolio ga vaqtincha src/pages/eski.tsx (getStaticProps + revalidate) qo'shdi. Sahifaning o'zi muammo emas edi, lekin build tur tekshiruvida yiqildi:

src/i18n/navigation.tsx(25,24): error TS2345: Argument of type 'Record<string, string | string[]> | null' is not assignable to parameter of type 'Record<string, string | string[] | undefined>'.
src/i18n/navigation.tsx(32,39): error TS2345: Argument of type 'string | null' is not assignable to parameter of type 'string'.
src/i18n/navigation.tsx(33,30): error TS2322: Type 'string | null' is not assignable to type 'string'.
src/komponentlar/TilAlmashtirgich.tsx(17,11): error TS2339: Property 'locale' does not exist on type '{ locale: string; } | null'.

pages/ papkasi paydo bo'lishi bilan useParams() va usePathname() ning turlari … | null ga o'zgardi. Sabab (Next hujjati, useSearchParams sahifasi): Pages Router'da bu hooklar ilk render'da null qaytarishi mumkin, aralash loyihada Next ikkala holatni hisobga oladi. Ya'ni bitta eski sahifa butun loyihadagi har hook chaqiruviga null tekshiruvini talab qiladi. Kanon faylni olib tashladi — portfolio da Pages Router kerak emas.

Saboq ko'chish uchun: pages/ dan app/ ga o'tishda bu tur xatolari kutiladi, ularni ?? "" kabi zaxira bilan yoki sahifalarni tezroq ko'chirib yoping.

6. Portfolio qadami: holat yo'q

Kanonda bu dars uchun kod yo'q: portfolio Next 16.4 da noldan yozilgan, ko'chirish kerak emas. Lekin har loyiha keyinchalik yangilanadi. AGENTS.md va README'da versiyalar qotirilgan (--save-exact), shuning uchun yangilash har doim ongli qadam.

7. Ko'p uchraydigan xatolar

8. Mashqlar

Mashqlar kurs/mashqlar/23/42-yangilash/ da. Jonli yechimlarni «Ishga tushir» bilan sinang.

1-mashq (oson): qaysi versiyada?

• params Promise bo'ldi — Next
• middleware.ts → proxy.ts — Next
• fetch sukut bo'yicha keshlanmay qoldi — Next
• next lint olib tashlandi — Next
• Pages Router'da build vaqtida ma'lumot oladigan funksiya —

2-mashq (o'rta): package.json ni tekshirish

Funksiya yozing: checkUpgrade(pkg, nodeVersion) — Next 16 ga o'tishga to'siqlarni qaytarsin: (1) Node 20.9 dan past bo'lsa — "Node 20.9+ kerak"; (2) skriptlarda next lint bo'lsa — "next lint olib tashlangan"; (3) react versiyasi 19 dan past bo'lsa — "React 19 kerak". Versiyalarni "^18.2.0" kabi satrdan raqamga ajrating (replace, split, Number). To'siq yo'q bo'lsa — "tayyor".

function major(version) {
  return version.replace(/^[^\d]*/, "").split(".").map(Number);
}

function checkUpgrade(pkg, nodeVersion) {
  const issues = [];
  const [nMajor, nMinor] = major(nodeVersion);
  if (nMajor < 20 || (nMajor === 20 && nMinor < 9)) {
    issues.push("Node 20.9+ kerak");
  }
  const scripts = Object.values(pkg.scripts);
  if (scripts.some((s) => s.includes("next lint"))) {
    issues.push("next lint olib tashlangan");
  }
  if (major(pkg.dependencies.react)[0] < 19) {
    issues.push("React 19 kerak");
  }
  return issues.length ? issues : ["tayyor"];
}

const oldPkg = {
  scripts: { lint: "next lint", build: "next build" },
  dependencies: { next: "^14.2.0", react: "^18.2.0" },
};
console.log(checkUpgrade(oldPkg, "v18.19.0"));
const newPkg = {
  scripts: { lint: "eslint --max-warnings=0" },
  dependencies: { next: "16.4.0", react: "19.3.0" },
};
console.log(checkUpgrade(newPkg, "v24.21.0"));

[ 'Node 20.9+ kerak', 'next lint olib tashlangan', 'React 19 kerak' ]
[ 'tayyor' ]

3-mashq (qiyin): Pages → App xaritasi

Funksiya yozing: toAppRoute(pagesPath) — Pages Router fayl yo'lini App Router yo'liga aylantirsin: pages/index.tsx → app/page.tsx, pages/blog/[slug].tsx → app/blog/[slug]/page.tsx, pages/api/xabar.ts → app/api/xabar/route.ts, pages/_app.tsx va pages/_document.tsx → app/layout.tsx. Beshta yo'lni sinang.

function toAppRoute(pagesPath) {
  const path = pagesPath
    .replace(/^pages\//, "")
    .replace(/\.tsx?$/, "");
  if (path === "_app" || path === "_document") {
    return "app/layout.tsx";
  }
  if (path.startsWith("api/")) return `app/${path}/route.ts`;
  const dir = path.replace(/(^|\/)index$/, "");
  return dir ? `app/${dir}/page.tsx` : "app/page.tsx";
}

const files = [
  "pages/index.tsx",
  "pages/blog/[slug].tsx",
  "pages/blog/index.tsx",
  "pages/api/xabar.ts",
  "pages/_document.tsx",
];
for (const f of files) console.log(`${f} -> ${toAppRoute(f)}`);

pages/index.tsx -> app/page.tsx
pages/blog/[slug].tsx -> app/blog/[slug]/page.tsx
pages/blog/index.tsx -> app/blog/page.tsx
pages/api/xabar.ts -> app/api/xabar/route.ts
pages/_document.tsx -> app/layout.tsx

4-mashq: Portfolio qadami — kichik tajriba

portfolio ingizning nusxasida (masalan yangi branch'da) src/pages/eski.tsx yarating — oddiy getStaticProps va sahifa komponenti bilan. npm run tip ni ishga tushiring: | null tur xatolari chiqdimi? Qaysi fayllarda? Keyin faylni o'chiring va branch'ni tashlab yuboring. Commit yo'q.

9. Real ishda

• Yangilash — doimiy ish. Katta jamoalarda "dependency upgrade" har chorakda rejalashtiriladi; Renovate yoki Dependabot har yangi versiyaga PR ochadi. Katta versiya — alohida loyiha: qo'llanma, codemod, testlar, preview deploy.
• Pages Router hali keng tarqalgan. Ishga kirganda uni o'qish ehtimoli yuqori; intervyuda "getStaticProps va getServerSideProps farqi?", "App Router'ga qanday ko'chirasiz?" deb so'rashadi.
• Bosqichma-bosqich ko'chish — app/ va pages/ yonma-yon: avval yangi sahifalar app/ da, keyin eskilari birma-bir. Bunda | null turlar va ikki xil layout tizimi vaqtincha birga yashaydi.
• AI agentlar — Next 16 qo'llanmasi yangilashni coding agent bilan qilishni ham taklif qiladi (AGENTS.md, node_modules/next/dist/docs/). Lekin oxirgi tekshiruv — build, test va git diff — baribir sizda.

Xulosa

• Katta versiyalar birma-bir ko'tariladi: qo'llanma → codemod → build va testlar → commit.
• 14 → 15: params, cookies(), headers() Promise; fetch va GET sukut bo'yicha keshlanmaydi; React 19.
• 15 → 16: proxy.ts, Turbopack sukut, next lint yo'q, Node 20.9+, revalidateTag ikki argument, slotlarga default.js.
• Codemod hisobotiga emas, natijaga qarang: "0 ok" bo'lsa ham fayl qayta nomlangan edi (biz ishga tushirdik).
• Pages Router: getStaticProps/getStaticPaths (build), getServerSideProps (har so'rov), _app va _document; aralash loyihada hooklar | null.

Keyingi dars: Yakuniy Next.js loyiha — portfolio v2 ni yakunlaymiz: arxitektura, texnologiya tanlovlari va ularning narxi, sifat natijalari, README va AGENTS.md.

Manbalar

• Next.js hujjati — Upgrading: version 15, version 16, Codemods: https://nextjs.org/docs/app/guides/upgrading (16.4.0 bilan kelgan nusxa, 2026-10-21 da o'qildi)
• Next.js hujjati — Pages Router: getStaticProps, getServerSideProps, Custom App, Custom Document: https://nextjs.org/docs/pages
• Next.js hujjati — useSearchParams (Pages Router'da null): https://nextjs.org/docs/app/api-reference/functions/use-search-params
• Kanon: portfolio v2 tajribasi — pages/eski.tsx va | null tur xatolari; @next/codemod@16.4.0 ikki transform'i — biz qayta ishga tushirdik (2026-10-21, Node 24.21.0).