Як працює Soft Navigation (клієнтська навігація) в Next.js App Router?

При переході за посиланням браузер не перезавантажує документ. Він відправляє фоновий fetch-запит за Flight Payload нової сторінки (із заголовком RSC: 1). React на клієнті парсить потік, завантажує відсутні JS-чанки клієнтських компонентів та здійснює узгодження (reconciliation) віртуального дерева, оновлюючи лише змінені сегменти та зберігаючи стейт незмінних компонентів.

Чи відбувається повторна гідратація серверних компонентів при Soft Navigation?

Ні. Серверні компоненти не мають клієнтського коду і не гідратуються зовсім. Браузерний Reconciler просто приймає готові віртуальні DOM-вузли з рядка 'J' протоколу Flight і напряму монтує їх у DOM. Гідратація виконується виключно для клієнтських компонентів, описаних маркерами 'I'.

Що відбувається при неспівпаданні версій деплою під час навігації (Version Skew)?

Якщо користувач знаходиться на старій версії сторінки, а на сервері викатився новий деплой, запит за RSC Payload поверне посилання на нові JS-чанки, яких немає в кеші старої версії. При виявленні помилки невідповідності маніфесту Next.js автоматично виконує жорстке перезавантаження (Hard Navigation), безшовно оновлюючи додаток до актуальної версії.

Що таке React Flight Protocol і чим він принципово відрізняється від класичного JSON?

React Flight — це спеціалізований потоковий протокол передачі віртуального дерева компонентів від сервера до клієнта. На відміну від JSON, він підтримує циклічні посилання, нативні об'єкти Date, Map, Set, BigInt, серіалізацію JSX-елементів (дерев компонентів), потокові нерозв'язані Promise, а також дескриптори клієнтських модулів (Client References) із зазначенням шляхів до JS-бандлів.

Чому функції (колбеки) не можна передавати через Flight Protocol, а Server Actions — можна?

Звичайні функції прив'язані до локального середовища виконання та замикань пам'яті, які неможливо передати мережею між різними рантаймами (Node.js та Browser). Server Actions — це не передача коду функції, а серіалізація криптографічно підписаного RPC-ідентифікатора (ID ендпоінта). Коли клієнт викликає такий action, він робить POST-запит на сервер, де вихідна функція і виконується.

Яка роль Client Component Manifest у процесі бандлінгу Turbopack?

Маніфест — це JSON-карта, що створюється збирачем на етапі компіляції. Вона зв'язує абстрактні ідентифікатори клієнтських компонентів у коді додатку з реальними хешованими шляхами до чанків у public-директорії. Завдяки маніфесту сервер знає, які саме скрипти потрібно включити в Resource Hints для браузера при зустрічі 'use client'.

Як React 19 Taint API взаємодіє з серіалізацією Flight Protocol?

При виклику experimental_taintObjectReference(msg, object) об'єкт реєструється у внутрішньому реєстрі безпеки React. Якщо в процесі серіалізації серверного дерева у Flight Protocol збирач зустрічає цей об'єкт у пропсах Client Component, процес серіалізації негайно переривається з помилкою безпеки, запобігаючи витоку даних у мережу.

Яким чином у Flight Protocol серіалізуються нерозв'язані Promise?

Сервер відправляє дескриптор промісу з унікальним ID (маркер 'P'). Клієнтський Reconciler створює очікувальний Promise у дереві. Коли сервер завершує асинхронну операцію, він надсилає чанк із цим же ID та готовими даними. Клієнтський хук React 19 use(promise) перехоплює відповідь та переводить Suspense-межу в стан готовності.

Глибоке занурення: RSC Protocol та Архітектура — Next.js 16 App Router

Навіщо це потрібно#

Для вирішення типових завдань фронтенд-розробнику часто вистачає базових евристик: «компоненти за замовчуванням серверні», а для інтерактивності потрібно додати 'use client'. Проте для Lead-архітекторів та Senior-інженерів поверхневого розуміння недостатньо.

Коли додаток масштабується до сотень маршрутів і мільйонів користувачів, неминуче виникають складні низькорівневі питання:

У якому фізичному форматі сервер передає відрендерене дерево клієнту, якщо це не чистий HTML і не класичний JSON?
Як браузер під час переходу між сторінками виконує узгодження (Reconciliation) без перезавантаження документа та зі збереженням стану сторонніх клієнтських компонентів?
Чому одні типи даних (нативні Date, BigInt, Map, Set, нерозв'язані Promise) вільно перетинають межу мережі, а функції та класи викликають фатальні помилки серіалізації?

Глибоке розуміння React Flight Protocol та внутрішньої будови збирача Turbopack дозволяє проєктувати високопродуктивні системи з мінімальним оверхедом і блискавично локалізувати архітектурні збої в продакшені.

Ментальна модель#

Рендеринг і доставка React Server Components — це не одноразова генерація HTML, а потоковий конвеєр, що зв'язує два рантайми (Node.js/Edge та Browser).

При первинному вході на сайт сервер віддає HTML-каркас (для миттєвого відображення першого контенту FCP) разом із потоком Flight Payload.

Проте при подальших переходах користувача за посиланнями <Link> браузер не перезавантажує HTML-сторінку. Натомість ініціюється Soft Navigation (М'яка навігація): браузер відправляє фоновий мережевий запит із заголовком RSC: 1 (або параметром ?_rsc=...), отримуючи чистий потік інструкцій Flight.

text

КЛІЄНТ (Браузер)                                СЕРВЕР (Node.js/Edge)
   │                                                   │
(1)│── Клік по посиланню <Link href="/analytics"> ────►│
   │   GET /analytics?_rsc=123 (Заголовок RSC: 1)      │
   │                                                   │
(2)│                                                   │ 1. Виконання Server Components
   │                                                   │ 2. Серіалізація у Flight Protocol
   │                                                   │    - Resource Hints: H
   │                                                   │    - Client References: I
   │                                                   │    - UI Virtual Tree: J
   │                                                   │
(3)│◄── Потік RSC Flight Payload (Chunks) ─────────────┤
   │                                                   │
(4)│ 1. Парсинг потоку Flight                          │
   │ 2. Turbopack довантажує потрібні JS-чанки (I)     │
   │ 3. React Reconciler узгоджує віртуальний DOM      │
   │ 4. Оновлення UI БЕЗ перезавантаження сторінки!    │
   │    (Стейт активних Client Components збережено)   │

Життєвий цикл обробки запиту в RSC Protocol

1. Виконання в Server Runtimeserver

Сервер запускає функції компонентів, розв'язує асинхронні запити до БД та генерує віртуальне дерево елементів.

2. Серіалізація в React Flight Wire Formatflight

Дерево перетворюється на рядковий потік. Серверні вузли стають JSON-тегами, а клієнтські — Client References дескрипторами.

3. Перевірка безпеки Taint APIsecurity

Рантайм React інспектує передані пропси. Якщо в потік потрапляє об'єкт із позначкою taint, серіалізація переривається помилкою безпеки.

4. Потокова доставка чанківstream

Чанки Flight передаються через HTTP-стрім. Браузер починає обробку перших рядків до завершення рендерингу всієї сторінки.

5. Узгодження (Reconciliation) та Гідратаціяclient

React на клієнті вбудовує нове піддерево в живий DOM, звіряючи ключі з Client Component Manifest, та активує інтерактивність.

ЧЕКПОІНТ #1

Перевірка розуміння: Механіка Soft Navigation в App Router

+15 XP

Що запитує браузер у сервера, коли користувач клікає по внутрішньому посиланню <Link href='/analytics'> в Next.js App Router?

Синтаксис та API: React Flight Protocol#

У мережевому потоці Flight Payload являє собою набір текстових рядків, розділених символом переведення рядка \n. Кожен рядок починається з префікса, що визначає тип інструкції:

text

H["/static/css/app.css","stylesheet"]
I["(app-pages-browser)/./components/Counter.tsx",["static/chunks/counter.js"],"Counter"]
J0:["$","div",null,{"className":"container","children":[
  ["$","h1",null,{"children":"Панель керування"}],
  ["$","$L1",null,{"initialCount":10}]
]}]

H (Resource Hint): Resource Hint для негайного фонового завантаження стилів та шрифтів.
I (Client Module Import): Запис Client Component Manifest, що вказує браузеру фізичний шлях до JavaScript-чанка клієнтського компонента.
J (JSON Element Tree): Серіалізоване дерево елементів. Символ $ позначає React.createElement, а $L1 вказує на клієнтський модуль із рядка I.

Інтерактивний розбір потоку Flight#

Інспектор React Flight Protocol (RSC Stream)

Аналізуйте сирий бінарно-текстовий протокол серіалізації React Server Components

STREAMING LIVE

Вихідний HTTP-запит м'якої навігації:

RSC: 1

Запитує Flight stream замість повного HTML

Next-Router-State-Tree

Передає клієнтський знімок для дифу дерева

Next-Router-Prefetch: 1

Прапорець передзавантаження через <Link>

Потокові чанки text/x-component:Клікніть на чанк

Client Reference (I)Client Reference Manifest (Директива 'use client')

1:I["./components/MetricCard.tsx",["chunks/metric_card_client.js"],"default"]

Serialized JSX AST (0)Серіалізоване дерево елементів (JSX Stream)

0:{"name":"AnalyticsPage","children":["$","div",null,{"className":"p-6","children":["$","$L1",null,{"metric":"visitors"}]}]}

Lazy Slot Promise ($L1)Розв'язання асинхронного Promise (Suspense Stream)

2:L1:{"value":14280,"status":"fresh","timestamp":1741859200}

Client Reference (I)

Client Reference Manifest (Директива 'use client')

Сервер не відправляє вихідний код MetricCard. Натомість він передає покажчик на бандл-чанк, який браузер має завантажити та гідратувати.

Архітектурна перевага:

Решта 90% коду сторінки залишається на сервері без роздування клієнтського бандлу (Zero-Bundle Size).

Next.js 16 оптимізація: Клієнтський парсер Flight Payload переписано на двофазний нативний парсер, що прискорило десеріалізацію на 350%.

Матриця серіалізації React Flight Protocol (Wire Format)

Критерий	Підтримується у Flight (Безпечно передавати)	Заборонено у Flight (Помилка серіалізації)
Примітивні типи	string, number, boolean, null, undefined, BigInt	Symbol (крім зареєстрованих через Symbol.for)
Складні структури	Plain Objects, Arrays, Map, Set, TypedArrays, ArrayBuffer	Екземпляри користувацьких класів (OOP Instances)
Тимчасові сутності	Date (зберігається як нативний об'єкт часу)	RegExp, Generator Functions
Асинхронні типи	Promise (стрімляться чанками та розгортаються через use())	AsyncGenerator, WebSockets, ReadableStream (безпосередньо в props)
Функції та код	Server Actions (з 'use server', передаються як RPC-посилання)	Звичайні клієнтські/серверні функції та обробники (onClick)
React-елементи	JSX Elements (children, слоти, згенеровані сервером)	React Context, mutable Ref об'єкти (useRef)

Практичні патерни#

Патерн 1: Безпечна проєкція DTO зі збереженням нативних типів#

React Flight нативно підтримує Date та BigInt. Ніколи не використовуйте деструктивний хак JSON.parse(JSON.stringify())! Проєктуйте вибірку через явний типізований DTO:

tsxlib/dto/order.ts (Безпечний DTO)

export interface OrderDTO {
  id: string;
  totalAmount: bigint;     // Flight нативно серіалізує BigInt!
  createdAt: Date;         // Flight нативно серіалізує Date!
  metadata: Map<string, string>; // Flight нативно серіалізує Map!
}

export function toOrderDTO(raw: {
  id: string;
  total: bigint;
  created_at: Date;
  meta: Record<string, string>;
}): OrderDTO {
  return {
    id: raw.id,
    totalAmount: raw.total,
    createdAt: raw.created_at,
    metadata: new Map(Object.entries(raw.meta)),
  };
}

tsxapp/orders/[id]/page.tsx (Server Component)

import { db } from '@/lib/db';
import { toOrderDTO } from '@/lib/dto/order';
import { ClientOrderView } from './ClientOrderView';

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function OrderPage({ params }: PageProps) {
  const { id } = await params;
  const rawOrder = await db.order.findUniqueOrThrow({ where: { id } });

  // Перетворюємо на безпечний DTO з нативними типами
  const orderDTO = toOrderDTO(rawOrder);

  // Передаємо клієнту: Date, BigInt та Map збережуться без втрат!
  return <ClientOrderView order={orderDTO} />;
}

Патерн 2: Server Actions як криптографічні RPC-дескриптори#

Коли функція з директивою 'use server' передається в клієнтський компонент (наприклад, через .bind()), рантайм React шифрує прив'язані аргументи за допомогою Action Closure Encryption:

tsxapp/users/page.tsx (Безпечний Server Action Prop)

import { deleteUserAction } from '@/app/actions/user';
import { DeleteUserButton } from './DeleteUserButton';

export default async function UsersPage() {
  const userId = 'usr_98741';

  // .bind() шифрує аргументи в закритий криптографічний токен усередині Flight Payload!
  // Клієнт бачить лише непрозоре RPC-посилання вигляду: $F1 = ["$ACTION_ID_123", ["usr_98741"]]
  const boundDelete = deleteUserAction.bind(null, userId);

  return <DeleteUserButton onDelete={boundDelete} />;
}

ЧЕКПОІНТ #2

Перевірка розуміння: Нативна серіалізація React Flight проти JSON

+15 XP

Чому виклик JSON.parse(JSON.stringify(data)) перед передачею даних із Server Component у Client Component вважається шкідливим антипатерном у сучасній розробці?

Поширені помилки#

Ошибка: Антипатерн JSON.parse(JSON.stringify()): руйнування нативних типів Flight

Спроба «очистити» об'єкти перед передачею клієнту через JSON.parse(JSON.stringify(data)) є грубою помилкою:

Об'єкти Date перетворюються на рядки ISO 8601, вимагаючи повторного new Date() на клієнті.
Значення BigInt викидають фатальний TypeError: Do not know how to serialize a BigInt.
Колекції Map та Set перетворюються на порожні об'єкти {}.

React Flight нативно підтримує Date, BigInt, Map, Set та ArrayBuffer!

Рішення: Проєктуйте вибірку через типізовані DTO без використання JSON.stringify.

Ошибка: Прихований витік даних та роздування Flight Payload при використанні .bind()

Коли ви прив'язуєте аргументи до Server Action для передачі в Client Component, Next.js зашифрує всі прив'язані аргументи та передасть їх клієнту всередині рядка W протоколу Flight. Якщо замкнути масив на 10 000 елементів або секретний ключ, бандл Flight роздується на мегабайти, а конфіденційні дані будуть відправлені на пристрій користувача.

Рішення: Передавайте в .bind() лише публічні скалярні ідентифікатори (ID сутності), а секретні ключі витягуйте на сервері безпосередньо всередині тіла Server Action.

tsxБезпечна передача ідентифікаторів у Server Action

// ❌ НЕБЕЗПЕЧНО: передача приватного ключа в bound action
// const boundAction = deleteUser.bind(null, userId, secretApiKey);

// ✅ ПРАВИЛЬНО: передавати лише публічний ID
// const boundAction = deleteUser.bind(null, userId);

Ошибка: Збій навігації при деплої нової версії (ChunkLoadError / Version Mismatch)

Користувач відкрив сайт на версії деплою v1. Ви викатили v2, де хеші JS-чанків змінилися. Користувач клікає по посиланню:

Браузер запитує ?_rsc=... та отримує Flight Payload від v2.
Flight Payload містить рядок I з хешем нового чанка chunk-v2-abc.js.
Браузер намагається завантажити цей чанк, але CDN або кеш віддають 404, або рантайм React стикається з розсинхронізацією дерева.

Як Next.js вирішує це під капотом: Next.js перехоплює збій узгодження версій та автоматично ініціює Hard Navigation (повне перезавантаження документа), непомітно оновлюючи вкладку користувача до версії v2.

Ошибка: Мутація пропсів на клієнті ламає повторну навігацію

Об'єкти, десеріалізовані з Flight Payload, заморожуються React (Object.freeze). Спроба напряму змінити властивість props.user.name = 'New' викине помилку в strict mode або призведе до неконсистентного стану Reconciler при повторному візиті на сторінку.

Питання зі співбесід#

Запитають на співбесіді8 запитань

Повʼязані теми

Server та Client Компоненти в Next.js: Архітектура двох світів Патерни композиції компонентів та Donut Pattern Потоковий рендеринг (Streaming SSR) та Suspense Partial Prerendering (PPR): гібридне передрендерення

Глибоке занурення: RSC Protocol та Архітектура

Навіщо це потрібно#

Ментальна модель#

1. Архітектура м'якої навігації (Soft Navigation)#

Синтаксис та API: React Flight Protocol#

Інтерактивний розбір потоку Flight#

Інспектор React Flight Protocol (RSC Stream)

Client Reference Manifest (Директива 'use client')

Практичні патерни#

Патерн 1: Безпечна проєкція DTO зі збереженням нативних типів#

Патерн 2: Server Actions як криптографічні RPC-дескриптори#

Поширені помилки#

Ошибка: Антипатерн JSON.parse(JSON.stringify()): руйнування нативних типів Flight

Ошибка: Прихований витік даних та роздування Flight Payload при використанні .bind()

Ошибка: Збій навігації при деплої нової версії (ChunkLoadError / Version Mismatch)

Ошибка: Мутація пропсів на клієнті ламає повторну навігацію

Питання зі співбесід#

Навіщо це потрібно#

Ментальна модель#

1. Архітектура м'якої навігації (Soft Navigation)#

Синтаксис та API: React Flight Protocol#

Інтерактивний розбір потоку Flight#

Інспектор React Flight Protocol (RSC Stream)

Client Reference Manifest (Директива 'use client')

Практичні патерни#

Патерн 1: Безпечна проєкція DTO зі збереженням нативних типів#

Патерн 2: Server Actions як криптографічні RPC-дескриптори#

Поширені помилки#

Ошибка: Антипатерн JSON.parse(JSON.stringify()): руйнування нативних типів Flight

Ошибка: Прихований витік даних та роздування Flight Payload при використанні .bind()

Ошибка: Збій навігації при деплої нової версії (ChunkLoadError / Version Mismatch)

Ошибка: Мутація пропсів на клієнті ламає повторну навігацію

Питання зі співбесід#