Практичний гайд по App Router у Next.js 16.4: межа між серверними й клієнтськими компонентами, Cache Components з use cache, cacheLife і cacheTag, Suspense, Server Actions, SEO, зображення, proxy.ts, деплой і пастки, що з'їдають бали Lighthouse.
- Опубліковано
- Читання
- 14 хв
- Автор
- Yaroslav Tsarenko

Цю статтю я вперше написав у травні 2026 року для Next.js 14. Відтоді вийшли Next.js 15 і 16, а 6 жовтня й Next.js 16.4 з React 19.3. Половина порад із першої версії тепер або застаріла, або шкідлива: fetch більше не кешується сам, middleware.ts став proxy.ts, revalidateTag з одним аргументом позначений як застарілий, а кешування перейшло на нову модель Cache Components. Тому я переписав текст під актуальну версію повністю.
Це гайд для команд, які тримають на App Router реальний продукт: сайт, кабінет, маркетплейс. Я розкладаю, де проводити межу між серверним і клієнтським кодом, як кешувати так, щоб це було видно в коді, що робити з мутаціями, SEO, зображеннями й деплоєм, і які помилки найчастіше коштують балів Lighthouse. Приклади я перевіряв у тестовому проєкті на Next.js 16.4.4, тож вивід збірки й заголовки відповіді нижче справжні; db і auth у коді — це заглушки вашого шару даних.
Що змінилось з часів Next.js 14
Коротко: App Router став простішим у моделі й суворішим у перевірках. Головні зміни, які впливають на код продукту:
| Тема | Next.js 14 | Next.js 16.4 |
|---|---|---|
| Кешування даних | fetch кешувався неявно |
нічого не кешується, поки ви не напишете "use cache" |
| Рендеринг сторінки | статичний або динамічний цілком | статична оболонка плюс динамічні частини в Suspense |
params, cookies(), headers() |
синхронні | тільки через await |
| Перехоплення запитів | middleware.ts на Edge |
proxy.ts на Node.js |
| Інвалідація | revalidateTag(tag) |
updateTag(tag) або revalidateTag(tag, profile) |
| Збірка | webpack | Turbopack за замовчуванням |
| Зображення | priority |
preload, qualities за замовчуванням [75] |
| Мінімальний Node.js | 18 | 20.9 |
Next.js 14
- Неявний кешfetch кешувався за замовчуванням
- middleware.tsEdge runtime
- Синхронні paramscookies() і headers() без await
- revalidateTag(tag)один аргумент
Next.js 16.4
- use cacheкеш лише там, де ви його оголосили
- proxy.tsNode.js runtime, функція proxy
- Асинхронні APIawait params, await cookies()
- updateTag і revalidateTag(tag, profile)свої зміни одразу або фонове оновлення
Найбільша зміна — Cache Components. У Next.js 16.4 команда фреймворку прямо пише, що рекомендує цю модель для кожного застосунку, create-next-app вмикає її за замовчуванням, а в Next.js 17 вона стане стандартом. Тобто питання вже не «чи переходити», а «коли і в якому порядку».
Серверні й клієнтські компоненти: де проводити межу
Базове правило не змінилось: кожен компонент за замовчуванням серверний, а "use client" ставиться тільки там, де потрібні стан, ефекти, обробники подій або API браузера. Але в першій версії статті я написав неточність, яку варто виправити.
Я стверджував, що клієнтський компонент у layout.tsx, який обгортає {children}, робить увесь застосунок клієнтським. Це не так. За документацією React, директива позначає межу в дереві модулів: клієнтським стає все, що цей файл імпортує. А серверні компоненти, передані йому як children чи інші пропси, залишаються серверними і приходять у браузер уже відрендереними.
На цьому сайті є саме такий приклад. Кореневий layout рендерить SiteChrome, маленький клієнтський компонент, який через usePathname() ховає навігацію й футер в адмінці. Футер передається йому як children і залишається серверним: його JavaScript не потрапляє в бандл. Проблема виникає інакше: коли клієнтський файл сам імпортує важкі компоненти, бібліотеки форматування дат чи markdown. Тоді вони їдуть у браузер разом із ним.
Практичні правила, якими я користуюсь:
- Клієнтський «острів» якомога нижче. Кнопка «Додати в кошик» може бути клієнтською, картка товару навколо неї — ні.
- Обгортки через
children. Провайдери теми, анімацій, аналітики приймають серверне дерево як пропс і нічого не імпортують із нього. - Секрети тільки на сервері. Пакет
server-onlyв модулі доступу до даних зламає збірку, якщо хтось випадково імпортує його в клієнтський компонент. - Серіалізовані пропси. Через межу передаються лише дані, які можна серіалізувати. Передавайте ID і потрібні поля, а не цілий запис із бази.
Кешування з Cache Components: use cache, cacheLife, cacheTag
У Next.js 14 кешування було неявним і складалося з чотирьох шарів, які взаємодіяли не завжди очевидно. У новій моделі все, що не позначено, виконується на кожен запит. Кешується тільки те, де ви явно написали "use cache". Вмикається модель у конфігурації:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
};
export default nextConfig;partialPrefetching у документації радять задавати явно: без нього збірка виводить попередження, а в наступній мажорній версії обидва прапорці зникнуть і стануть поведінкою за замовчуванням.
Далі кеш оголошується там, де отримуються дані. Аргументи функції автоматично стають частиною ключа кешу:
import { cacheLife, cacheTag } from "next/cache";
export type Post = { slug: string; title: string; body: string };
export async function getPosts(): Promise<Post[]> {
"use cache";
cacheLife("days");
cacheTag("posts");
return db.posts.findMany({ orderBy: { publishedAt: "desc" } });
}
export async function getPost(slug: string): Promise<Post | undefined> {
"use cache";
cacheLife("days");
cacheTag("posts", `post-${slug}`);
return db.posts.findUnique({ where: { slug } });
}cacheLife задає три часи: stale (скільки браузер показує збережене без запиту), revalidate (після чого сервер оновлює дані у фоні) і expire (після чого наступний запит чекає свіжих даних). Вбудовані профілі з документації по кешуванню:
| Профіль | stale |
revalidate |
expire |
Для чого |
|---|---|---|---|---|
default |
5 хв | 15 хв | ніколи | якщо cacheLife не викликали |
seconds |
30 с | 1 с | 1 хв | майже реальний час |
minutes |
5 хв | 1 хв | 1 год | стрічки, новини |
hours |
5 хв | 1 год | 1 день | каталог, залишки |
days |
5 хв | 1 день | 1 тиждень | статті, сторінки послуг |
weeks |
5 хв | 1 тиждень | 30 днів | розсилки, подкасти |
max |
5 хв | 30 днів | 1 рік | юридичні сторінки, архів |
Три речі, які варто знати до першого деплою:
- Завжди викликайте
cacheLife. Без нього діє профільdefault, а у вкладених кешах тривалість зовнішнього може непомітно скоротитись до внутрішнього. - Короткий кеш стає «дірою».
seconds,revalidate: 0абоexpireменше 5 хвилин не потрапляють у статичну оболонку і рахуються на запит. - Звичайний
"use cache"під час виконання живе в пам'яті інстансу. На serverless такий кеш не переживає між запитами. Для спільного кешу між інстансами є"use cache: remote", для даних конкретного користувача з cookies —"use cache: private".
Якщо продукт обслуговує кількох клієнтів або мовні версії, стежте, щоб тенант завжди потрапляв у ключ кешу. Чому це важливо і що змінив листопадовий реліз безпеки, я розібрав у статті про витоки даних через use cache.
Перша помилка, яку ви побачите: статична оболонка і Suspense
Коли Cache Components увімкнено, Next.js під час збірки рендерить кожен маршрут і збирає з нього статичну оболонку: HTML, який можна віддати з CDN одразу. Усе, що залежить від запиту, має бути або закешоване, або загорнуте в <Suspense>. Якщо ні, збірка падає. Ось сторінка кабінету, яка читає cookie напряму:
import { cookies } from "next/headers";
export default async function Account() {
const session = (await cookies()).get("session")?.value;
return <p>{session ? "Signed in" : "Signed out"}</p>;
}Вивід next build на 16.4.4:
Error: Route "/account": Next.js encountered uncached or runtime data during prerendering.
`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.
Ways to fix this:
- [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
- [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)
- [block] Set `export const instant = false` to allow a blocking routeВиправлення — винести читання cookie в окремий компонент і загорнути його в Suspense. Заголовок і каркас сторінки потраплять в оболонку, статус сесії прийде потоком:
import { Suspense } from "react";
import { cookies } from "next/headers";
async function SessionStatus() {
const session = (await cookies()).get("session")?.value;
return <p>{session ? "Signed in" : "Signed out"}</p>;
}
export default function Account() {
return (
<main>
<h1>Account</h1>
<Suspense fallback={<p>Checking session...</p>}>
<SessionStatus />
</Suspense>
</main>
);
}Та сама помилка трапилась у мене на сторінці редагування /blog/[slug]/edit, де немає generateStaticParams: динамічні params теж рахуються даними запиту. Рішення з документації — не робити await params на рівні сторінки, а передати проміс усередину Suspense:
import { Suspense } from "react";
import { RenameForm } from "./RenameForm";
export default function EditPage({ params }: PageProps<"/blog/[slug]/edit">) {
return (
<Suspense fallback={<p>Loading editor...</p>}>
{params.then(({ slug }) => (
<RenameForm slug={slug} />
))}
</Suspense>
);
}Після виправлень збірка показує, що вийшло з кожного маршруту:
Route (app) Revalidate Expire
┌ ◐ / 1d 1w
├ ○ /_not-found
├ ◐ /account
├ /blog/[slug]
│ ├ ◐ /blog/[slug]
│ ├ ○ /blog/hello 1d 1w
│ └ ○ /blog/cache 1d 1w
└ /blog/[slug]/edit
└ ◐ /blog/[slug]/edit
○ (Static) prerendered as static content
◐ (Partial Prerender) prerendered as static HTML with dynamic server-streamed contentГоловна сторінка тут позначена ◐: список статей закешований на добу (1d, 1w — це revalidate і expire профілю days), а привітання з cookie приходить потоком. У HTML, який віддає сервер, уже є <h1>Blog</h1>, посилання на статті й заглушка <p>...</p>. Сторінки статей, перелічені в generateStaticParams, повністю статичні, і відповідь для /blog/hello прийшла з такими заголовками:
x-nextjs-cache: HIT
x-nextjs-stale-time: 300
Cache-Control: s-maxage=86400, stale-while-revalidate=518400Тобто CDN тримає сторінку добу і ще шість днів може віддавати її, оновлюючи у фоні. Саме це й хочеться бачити на контентних сторінках.
Мутації: Server Actions, updateTag і revalidateTag
Server Actions — це функції з "use server", які викликаються з форм або переходів. У Next.js 16 з'явились два API, що закривають стару проблему «зберіг, а на сторінці старе»:
"use server";
import { revalidateTag, updateTag } from "next/cache";
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
export async function renamePost(slug: string, title: string) {
const session = await auth();
if (!session?.user) return { ok: false as const, error: "Sign in first" };
if (title.trim().length < 3) return { ok: false as const, error: "Title is too short" };
const post = await db.posts.findFirst({ where: { slug, authorId: session.user.id } });
if (!post) return { ok: false as const, error: "Not found" };
await db.posts.update({ where: { id: post.id }, data: { title: title.trim() } });
updateTag(`post-${slug}`);
revalidateTag("posts", "max");
return { ok: true as const };
}updateTag одразу робить запис кешу недійсним, і Next.js у тій самій відповіді надсилає перемальовану сторінку: автор бачить новий заголовок без додаткового запиту. revalidateTag("posts", "max") позначає список статей застарілим: наступні відвідувачі отримають старий список, поки новий генерується у фоні. Для вебхука з CMS у Route Handler підходить тільки другий варіант, бо updateTag працює лише в Server Actions.
Клієнтська форма з useActionState з React 19 показує стан відправлення й помилку без жодного useEffect:
"use client";
import { useActionState } from "react";
import { renamePost } from "@/app/actions";
type State = { ok: boolean; error?: string } | null;
export function RenameForm({ slug }: { slug: string }) {
const [state, action, pending] = useActionState<State, FormData>(
async (_prev, formData) => renamePost(slug, String(formData.get("title") ?? "")),
null,
);
return (
<form action={action}>
<input name="title" required />
<button disabled={pending}>{pending ? "Saving..." : "Save"}</button>
{state?.error && <p role="alert">{state.error}</p>}
</form>
);
}Найважливіше про безпеку. Документація по Server Actions прямо каже: кожна дія — це POST-ендпоінт, до якого може звернутися будь-хто, хто відтворить запит. Те, що форма показується лише авторизованим, не є захистом. Тому всередині кожної дії: перевірка сесії, перевірка прав на конкретний запис, валідація вводу і повернення лише тих полів, які потрібні інтерфейсу. Ще дві деталі: клієнт виконує дії по черзі, тож Promise.all з кількох дій не дасть паралельності, а розмір тіла запиту за замовчуванням обмежено 1 МБ.
Коли я перебудовував маркетплейс AllShip AI на Next.js 16, саме такий аудит займав помітну частину роботи: я перевірив на права доступу 109 точок входу, включно з діями й API.
Route Handlers (app/api/*/route.ts) залишаються для того, що викликають ззовні: вебхуки, інтеграції, мобільний клієнт. Внутрішні форми — через Server Actions. З Cache Components GET-обробники підкоряються тій самій моделі пререндерингу, що й сторінки.
Метадані й SEO
Metadata API майже не змінився, але кілька речей я роблю на кожному проєкті:
metadataBaseі шаблон заголовка в кореневому layout. На цьому сайті цеmetadataBase: new URL(profile.url)іtemplate: "%s — Yaroslav Tsarenko", тож кожна сторінка задає лише свою частину.alternates.canonicalіlanguagesна кожній сторінці. Статті тут мають canonical і hreflang для англійської й української версій, аsitemap.tsдодає ті самі альтернативи.generateMetadataз тими самими кешованими функціями, що й сторінка. Дані запитуються один раз, а в моделі Cache Components некешовані запити вgenerateMetadataдають ті самі помилки збірки, що й у сторінці.
Окремо про ботів. З частковим пререндерингом метадані можуть приходити потоком після оболонки. Деякі краулери так не вміють, тож Next.js визначає їх за user agent і рендерить для них сторінку повністю на запит. Наслідок: джерела даних мають бути доступні в рантаймі, інакше бот отримає 500, а не сторінку. Якщо ваш сайт має приводити клієнтів із пошуку й AI-відповідей, важливо, щоб текст був у HTML із сервера; про це я писав у статті як сайту отримувати ліди, коли відповідає AI.
Зображення і шрифти
Тут найпростіше втратити бали без жодної помилки в консолі.
priorityзамінили наpreload. У Next.js 16priorityзастарів. Документація радить для головного зображення першого екрана здебільшогоloading="eager"абоfetchPriority="high", аpreload— коли треба почати завантаження ще з<head>.- Справжній
sizes. Без нього браузер дляfill-зображень бере ширину вікна. Картка в сітці з трьох колонок — цеsizes="(max-width: 768px) 100vw, 33vw", а не100vw. qualitiesтепер[75]. Будь-якийqualityокруглюється до найближчого дозволеного значення. Хочете 90 для портфоліо — додайте його вimages.qualities.- Шрифти через
next/font. На цьому сайті основний шрифт підключено зdisplay: "swap", а декоративний курсив — зdisplay: "optional": якщо він не встиг, сторінка не стрибає.
На Tresor.tech я зробив понад 20 продакшен-інтерфейсів, і саме поділ коду та робота із зображеннями скоротили час завантаження приблизно на 30%. Жодного магічного прапорця там не було: правильні розміри, формати й ліниве завантаження всього, що нижче першого екрана.
proxy.ts замість middleware.ts
У Next.js 16 middleware.ts перейменували на proxy.ts, а функцію — на proxy. Вона працює на Node.js runtime. Мінімальний приклад, перевірений на тестовому проєкті:
import { NextResponse, type NextRequest } from "next/server";
export function proxy(request: NextRequest) {
if (!request.cookies.has("session")) {
const login = new URL("/login", request.url);
login.searchParams.set("next", request.nextUrl.pathname);
return NextResponse.redirect(login);
}
return NextResponse.next();
}
export const config = {
matcher: ["/account/:path*"],
};$ curl -sI http://localhost:3000/account
HTTP/1.1 307 Temporary Redirect
location: /login?next=%2FaccountПравила ті самі, що й раніше, тільки тепер вони записані в документації: proxy не для повільних запитів у базу і не заміна авторизації. Він годиться для оптимістичної перевірки «є cookie чи ні», A/B-перенаправлень і заголовків. Справжня перевірка прав — у шарі доступу до даних і в кожній Server Action. Тримайте matcher вузьким, а прості редиректи переносьте в redirects у next.config.ts. Цей сайт так і робить: старі URL кейсів і блогу перенаправляються з конфігурації, і proxy.ts тут взагалі немає.
Деплой: що змінюється за межами коду
- Кеш живе в межах деплою. Ключ кешу включає ID збірки, тож після нового деплою записи
use cacheпочинаються з нуля. Це нормально, але враховуйте першу хвилю запитів. - Serverless і пам'ять. На serverless звичайний рантайм-кеш живе в пам'яті одного інстансу. Якщо ви самі хостите кілька інстансів, налаштуйте cache handler або використовуйте
"use cache: remote"там, де висока частка влучань. - Ключ шифрування дій. Для кількох інстансів задайте однаковий
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY. ID дій змінюються між деплоями, тож користувач зі старою вкладкою може отримати «Failed to find Server Action». Покажіть йому кнопку «оновити», а не білий екран. - Не лише Vercel. З Next.js 16.2 стабільний Adapter API для інших платформ. Цей сайт працює на Vercel, але модель та сама і при self-hosting.
- Безпекові релізи за графіком. З липня 2026 року Next.js випускає патчі безпеки за розкладом; реліз 3 листопада закриває сім вразливостей середньої критичності. Закладіть щомісячне оновлення в процес, так само як оновлення рантайму в моєму гайді по Node.js 26 LTS.
Пастки, що коштують балів Lighthouse
Пороги Core Web Vitals від web.dev не змінились: LCP до 2,5 секунди, INP до 200 мілісекунд, CLS до 0,1 для 75% відвідувань. Ось що найчастіше їх ламає в App Router:
| Пастка | Що страждає | Виправлення |
|---|---|---|
| Головне зображення без пріоритету | LCP | loading="eager" або fetchPriority="high" |
sizes не задано або 100vw у сітці |
LCP, трафік | реальні ширини за брейкпоінтами |
| Suspense навколо першого екрана | LCP, CLS | заголовок і головний блок в оболонці, Suspense нижче |
| Заглушка іншої висоти, ніж контент | CLS | скелетон із тими самими розмірами |
| Клієнтський файл імпортує важкі бібліотеки | INP, TBT | серверний компонент або next/dynamic для рідкісного |
Шрифт без next/font |
CLS | next/font з display |
| Блокуючий маршрут без потреби | TTFB, LCP | use cache для спільних даних, Suspense для персональних |
Правило зі старої версії статті залишається: те, що є LCP-елементом, не ховайте за Suspense. Потік добрий для того, що нижче першого екрана, а не для головного заголовка.
Як мігрувати з Next.js 14: покроково
- Оновіться без нової моделі.
npx @next/codemod@canary upgrade latestпереводитьparams,cookies()іheaders()на асинхронні виклики. Перейменуйтеmiddleware.tsнаproxy.ts, додайте другий аргумент уrevalidateTag, замінітьpriorityнаpreloadчиfetchPriority. - Отримайте зелену збірку на старій моделі. Ті самі маршрути, тести, заміри Lighthouse до й після. Цей сайт, до речі, досі працює саме так: статті генеруються через
generateStaticParamsзrevalidate = 86400, адмінка оновлюється черезrevalidatePath. Для контентного сайту це цілком робочий варіант. - Увімкніть
cacheComponentsіpartialPrefetching. Збірка сама перелічить маршрути, яким бракує Suspense або кешу. - Виправляйте маршрут за маршрутом. Спільні дані — у функції з
"use cache"іcacheLife, персональні — в Suspense. - Перенесіть інвалідацію на теги.
cacheTagна читанні,updateTagу формах,revalidateTag(tag, "max")у вебхуках.
Заодно варто оновити й TypeScript: з Next.js 16.3 next build перевіряє типи через TypeScript 7 у кілька разів швидше. Що при цьому ламається в tsconfig і ESLint — у статті про міграцію на TypeScript 7.
Якщо проєкт зібрали швидко за допомогою AI і тепер він повільний чи нестабільний, такий перехід зазвичай поєднують із ревізією коду. Як зрозуміти, що час кликати розробника, я розписав у статті про vibe coding і MVP.
Підсумок
App Router у версії 16.4 нарешті став тим, чим обіцяв бути: за замовчуванням усе свіже, кеш оголошується явно поруч із даними, а сторінка складається зі статичної оболонки й динамічних частин. Ціна — суворіша збірка, але кожна її помилка вказує на реальну проблему швидкості.
Почніть із малого: оновіть Next.js до актуального патча, перевірте priority, sizes і Suspense на першому екрані, а потім увімкніть Cache Components в окремій гілці й подивіться, що скаже збірка. Якщо хочете пройти цей шлях разом, від аудиту до міграції, подивіться, як я працюю з розробкою на Next.js, або напишіть мені.
Було корисно?
– вподобань · – переглядів
Часті запитання
Чи варто вмикати Cache Components в наявному проєкті на Next.js?
Починаючи з Next.js 16.4 команда Next.js рекомендує Cache Components для всіх застосунків, а в Next.js 17 ця модель стане стандартною. Для нового проєкту вмикайте одразу. Для наявного спершу оновіться до 16.x на старій моделі, а потім переводьте маршрути поступово: збірка сама покаже, де бракує Suspense або use cache.
Чим updateTag відрізняється від revalidateTag?
updateTag працює тільки в Server Actions і одразу робить кеш недійсним, тож користувач бачить свою зміну в тій самій відповіді. revalidateTag(tag, profile) працює і в Route Handlers, віддає застарілі дані, поки свіжі генеруються у фоні, і підходить для вебхуків із CMS.
Чи замінює proxy.ts файл middleware.ts?
Так. У Next.js 16 middleware.ts перейменували на proxy.ts, функцію експортують як proxy, і вона працює на Node.js runtime. middleware.ts ще працює для Edge, але позначений як застарілий. Для простих редиректів краще redirects у next.config.ts.
Чому з Cache Components збірка падає з помилкою про uncached data?
Бо маршрут читає cookies(), headers(), params, searchParams або некешований запит поза межами Suspense, і Next.js не може зібрати статичну оболонку сторінки. Оберніть такий компонент у Suspense, закешуйте дані через use cache або, якщо маршрут справді має блокувати, вимкніть перевірку для нього явно.
Яка версія Next.js актуальна в листопаді 2026?
Остання стабільна гілка 16.4, на момент написання це 16.4.4. Next.js 16.4 вийшов 6 жовтня 2026 року з React 19.3. Безпекові релізи тепер виходять за графіком, найближчий запланований на 3 листопада 2026 року.