Миграции версий React: проект — это аудит зависимостей

17 → 18: createRoot меняет поведение, а не только API

Оставить ReactDOM.render на React 18 — значит запустить приложение в легаси-режиме с предупреждением об устаревании и без какого-либо нового поведения; настоящий апгрейд — переход на createRoot, и он несёт одно тихое семантическое изменение, породившее целый класс продакшен-багов: автоматический батчинг везде. В 17 несколько вызовов setState сливались в один рендер только внутри обработчиков событий React; в таймаутах, промисах и нативных слушателях каждый setState синхронно прогонял собственный рендер. Код незаметно зависел от этого промежуточного коммита:

// React 17, легаси-рут: setOpen коммитится синхронно прямо здесь,
// поэтому к следующей строке модалка уже в DOM.
setTimeout(() => {
  setOpen(true);
  const h = panelRef.current.offsetHeight; // меряет настоящую панель
  setHeight(h);
}, 0);

// React 18, createRoot: оба апдейта сливаются в ОДИН рендер.
// panelRef.current — всё ещё СТАРОЕ дерево, offsetHeight читает мусор.
// Аварийный люк, когда коммит правда нужен немедленно:
flushSync(() => setOpen(true)); // коммитит до следующей строки

Класс багов коварен тем, что ничего не падает: измерение читает устаревший layout, аналитика стреляет один раз вместо двух, тест проверяет промежуточный рендер, которого больше не существует. flushSync возвращает семантику 17 для одного апдейта ценой синхронного коммита — применяйте его к считанным настоящим случаям «измерить после обновления», а не как ковровое лечение.

StrictMode — линтер миграции

Dev-режим StrictMode в React 18 прогоняет каждое монтирование как setup → cleanup → setup: эффекты срабатывают, их cleanup выполняется, затем они срабатывают снова. Команды, столкнувшись с этим при миграции, видят удвоенные WebSocket-соединения, удвоенные события аналитики, удвоенные подписки — и соблазнительный диагноз звучит как «StrictMode сломал приложение, выключим его». Правильное прочтение обратное: эффекты, ломающиеся под двойным прогоном, были сломаны и до него. Любой эффект, чей cleanup не отменяет setup в точности, неверно ведёт себя и в продакшене — при ремаунте роутов, при навигации назад/вперёд и под любой будущей фичей React, сохраняющей и восстанавливающей состояние компонентов. StrictMode — это фаззер контракта setup/cleanup, и потому самый дешёвый инструмент миграции: включите его в dev до апгрейда, почините каждый удвоенный сайд-эффект — и вы заранее оплатили класс багов, который автоматический батчинг и ремаунты иначе вскрывали бы в продакшене по одному тикету за раз.

React 19: удаления, ref как prop и путь к Компилятору

React 19 — релиз удалений. API, годами выдававшие предупреждения, исчезли: defaultProps у функциональных компонентов (используйте параметры по умолчанию), строковые refs, легаси-контекст (contextTypes / getChildContext), propTypes (теперь полностью игнорируются) и старые точки входа DOM — ReactDOM.render, hydrate, unmountComponentAtNode, findDOMNode. react-test-renderer объявлен устаревшим. Единственное добавление, меняющее повседневный код: ref — обычный prop функционального компонента, так что forwardRef превращается в церемонию, которую можно удалить:

// 18: церемония-обёртка
const Input = forwardRef((props, ref) => <input ref={ref} {...props} />);
// 19: ref приходит как любой другой prop
function Input({ ref, ...props }) { return <input ref={ref} {...props} />; }

React Compiler едет следом за 19 как опциональный шаг сборки: он автоматически мемоизирует компоненты, соблюдающие правила, и путь его внедрения повторяет форму самой миграции — сначала линт (расширенные правила eslint-plugin-react-hooks показывают, какие файлы нарушают Rules of React), затем включение каталог за каталогом, а не большим взрывом. Компонент, ломающийся под Компилятором, как и эффект, ломающийся под StrictMode, нарушал правила и раньше — инструмент лишь сделал это видимым.

Процесс: сначала deps, codemod-ы честно, канарейка с RUM

Аудит зависимостей идёт первым, потому что зависимости доминируют в сроках. Перечислите каждый пакет с peer-зависимостью react и рассортируйте по категориям смертного списка: тестовые фреймворки, пришитые к внутренностям React (похороны enzyme — смерть тестового фреймворка — самая частая скрытая стоимость), библиотеки на удалённых API (легаси-контекст, строковые refs, findDOMNode) и пакеты, чьи поддерживаемые версии требуют нового мажора React, пока остальные ваши deps требуют старого. По каждому пакету варианты: совместимый мажор существует (обновить), не существует (заменить, форкнуть или выпилить фичу), пакет внутренний (заложить переписывание). Этот аудит — таблица, собираемая за два дня, и именно она превращает «недели две, наверное» в честный план.

Codemod-ы (автоматизированные скрипты переименования кода) покрывают синтаксис, а не семантику. Официальная коллекция react-codemod (плюс миграционный рецепт React 19) выполняет механические переименования — обновление импортов, ReactDOM.render → createRoot, замену строковых refs, defaultProps → параметры по умолчанию. Чего ни один codemod не чинит: эффект, опирающийся на небатченные коммиты; тест, проверяющий промежуточные рендеры; подписку без cleanup. Прогоните codemod-ы — и заложите настоящее инженерное время на поведенческую разницу.

Раскатывайте как любой рискованный деплой. Отправьте обновлённую сборку на канареечное кольцо в 1% с RUM, следящим за тремя сигналами против контрольного кольца: частота JS-ошибок, частота расхождений гидрации и p75 INP/LCP. Наращивайте 1 → 10 → 50 → 100 за несколько дней; откат — перепиновка предыдущей сборки. Команды, которые «обновляют в ветке и мёржат, когда зелено», ставят на своё тестовое покрытие всю пользовательскую базу; команды с постепенным раскатом — один её процент.

Вместе эти четыре шага — аудит, codemod-ы, обкатка StrictMode, канареечный раскат — образуют единый конвейер: пропустите аудит и смертный список обнаружится в середине раската; пропустите канарейку и тихая батчинг-регрессия доедет до 100% пользователей прежде, чем кто-то заметит.

Цена отставания накапливается. Старый мажор не получает фич и на практике не получает патчей; диапазоны peer-зависимостей экосистемы уезжают вперёд, и ваше дерево зависимостей замерзает на последних версиях, поддерживающих ваш React, — вместе с их исправлениями безопасности. Найм усугубляет: кандидаты знают актуальный React. Честные сроки для большого приложения — недели-месяцы, и доминируют в них зависимости; и сроки растут, чем дольше ждать, потому что каждый пропущенный мажор добавляет собственный смертный список.