Миграция на React 18: подробное руководство по обновлению и запуску новых возможностей

TL;DR

React 18 добавляет конкурентную отрисовку, улучшенные возможности Suspense и серверную стриминговую отрисовку. Обновление обычно требует: обновить npm-пакеты, перейти на новый Root API (createRoot/hydrateRoot) и проверить поведение в Strict Mode и при автоматическом батчинге. Для сложных проектов полезен поэтапный план миграции и контрольный список.

Важно: сами новые возможности включаются по явному переходу на новый Root API — пока вы не измените точки входа, приложение будет вести себя как в React 17.

Быстрые ссылки

• Установка React 18
• Активация возможностей React 18: новый Root API
• Замена callback в render
• Отладка проблем после обновления
• Серверная отрисовка (SSR)
• Начало использования фич React 18
• Сводка и рекомендации

О чём это руководство

React 18 развивает известный фреймворк компонентов JavaScript, вводя конкурентную (concurrent) отрисовку и расширения для Suspense. Это руководство объясняет, как безопасно обновить существующие проекты, какие изменения ожидать и какие приёмы помогут предотвратить падения в продакшне.

Коротко — миграция обычно проста для маленьких и средних приложений, но большие кодовые базы с комплексными зависимостями и побочными эффектами могут потребовать дополнительной проверки и локальных правок.

Установка React 18

Перед любыми изменениями обновите зависимости проекта через npm или yarn:

$ npm install react@latest react-dom@latest

После установки вы можете запустить приложение без любых правок. Пока вы не поменяли точки входа (entrypoints), приложение будет работать с поведением React 17. Это даёт безопасную возможность подготовиться и протестировать проект.

$ npm start

Примечание: новые возможности включаются при переходе на новый Root API. Пока что вы увидите предупреждение в консоли разработки, но функциональность останется прежней.

Активация возможностей React 18: новый Root API

Если вы используете React 18, не меняя код, вы увидите предупреждение в браузерной консоли в режиме разработки:

ReactDOM.render is no longer supported in React 18. Use createRoot instead. Until you switch to the new API, your app will behave as if it's running React 17.

Это предупреждение можно проигнорировать временно. Чтобы включить новые фичи (конкурентная отрисовка, улучшенная Suspense и т.д.), нужно заменить старый вызов ReactDOM.render() на новый Root API.

Найдите в точке входа (например, index.js или app.js) код, похожий на этот:

import App from "./App.js";

import ReactDOM from “react-dom”;

const container = document.getElementById(“react”);

ReactDOM.render(, container);

Это типичный код инициализации. Чтобы перейти на Root API, замените его на:

import App from "./App.js";

import {createRoot} from “react-dom/client”;

const container = document.getElementById(“react”);

const root = createRoot(container);

root.render();

Разница концептуальна: старый API выполнял единоразовую императивную отрисовку. Новый API создаёт объект root, который управляет жизненным циклом дерева React. Этот подход открывает доступ к конкурентной отрисовке и новым возможностям библиотеки.

Размонтирование (unmount)

Если в коде встречается ReactDOM.unmountComponentAtNode(), замените его на метод unmount() у самого root:

// Before

import App from “./App.js”;

import ReactDOM from “react-dom”;

const container = document.getElementById(“react”);

ReactDOM.render(, container);

ReactDOM.unmountComponentAtNode(container);

// After

import App from “./App.js”;

import {createRoot} from “react-dom/client”;

const container = document.getElementById(“react”);

const root = createRoot(container);

root.render();

root.unmount();

Замена проста: у вас теперь объект root, и для него доступен метод unmount().

Замена render-callbacks

В старом API ReactDOM.render() поддерживал необязательный callback — функцию, вызываемую после того, как корневой узел отрисовался:

import App from "./App.js";

import ReactDOM from “react-dom”;

const container = document.getElementById(“react”);

ReactDOM.render(, container, () => console.log(“Rendered!”));

В React 18 у корневого API нет прямого эквивалента callback, потому что точный момент завершения отрисовки может быть не детерминирован (ввиду частичной гидрации и стриминга на сервере). Если вам нужно логировать или запускать код после монтирования, используйте ref-функции или эффекты в компонентах.

Пример использования функц‑ref в качестве обходного пути:

import {createRoot} from "react-dom/client";

const App = ({callback}) => (

);

const container = document.getElementById(“react”);

const root = createRoot(container);

root.render( console.log(“Rendered!”)} />);

React вызывает функциональные refs при монтировании. Установка ref на корневой узел позволяет отследить момент, когда DOM-элемент доступен.

Отладка проблем после обновления

После перехода на React 18 протестируйте приложение полностью. Ниже — список частых причин проблем и способы их решения.

1) Проверьте Strict Mode

Если приложение обёрнуто в , вы можете заметить отличия в режиме разработки. Strict Mode в React 18 дополнительно проверяет устойчивость состояния при повторных монтированиях. Он имитирует поведение с удалением и повторным монтированием компонентов, чтобы выявить проблемы с восстановлением состояния.

Краткое определение: Strict Mode — режим разработки, который помогает найти потенциально небезопасные побочные эффекты.

Что делать:

• Временно отключите , чтобы проверить, связаны ли ошибки с повторными монтированиями.
• Исправьте эффекты, которые не корректно очищают внешние ресурсы или подписки.
• Убедитесь, что компоненты не зависят от «одноразовых» побочных эффектов при монтировании.

Важно: отключать Strict Mode в продакшне не рекомендуется — лучше устранить корень проблемы.

2) Поддержка автоматического батчинга (automatic batching)

React 18 расширяет область применения батчинга обновлений состояния. Если раньше batched updates работали только в обработчиках событий React, теперь батчинг применяется и к обновлениям из нативных событий, setTimeout, промисов и т.д.

Коротко: автоматический батчинг объединяет несколько вызовов setState в одну перерисовку.

Пример, который меняет поведение:

const Component = () => {

const [query, setQuery] = useState(“”);

const [queryId, setQueryId] = useState(“”);

const [queryCount, setQueryCount] = useState(0);

const handleSearch = query => {

fetch(query).then(() => {

setQuery(“demo”);

setQueryCount(1);

// В React 17 sets к “query-1”

// В React 18 sets к “query-0” — предыдущее обновление состояния батчится с этим

setQueryId(query-${queryCount});

});

}

};

Решения:

- Если ожидается последовательное немедленное применение обновлений, используйте flushSync() из react-dom — он заставит выполнить обновления синхронно.

Пример:

const Component = () => {

const [query, setQuery] = useState("");

const [queryId, setQueryId] = useState("");

const [queryCount, setQueryCount] = useState(0);

const handleSearch = query => {

fetch(query).then(() => {

flushSync(() => {

setQuery("demo");

setQueryCount(1);

});

// Установит "query-1"

setQueryId(`query-${queryCount}`);

});

}

};

• Лучше переработать логику так, чтобы не полагаться на немедленное наблюдение за промежуточным состоянием. Используйте функциональные обновления состояния (prev => …) или эффект, который реагирует на изменение значения.

3) Удалённые и неподдерживаемые API

Некоторые API больше не поддерживаются. Основные моменты:

• unstable_changedBits удалён — опция для отключения обновлений контекста больше не доступна.
• Полифилл Object.assign() удалён из поставки React — при поддержке очень старых браузеров добавьте пакет object-assign вручную.
• Internet Explorer официально не поддерживается. Если вам обязателен IE, не обновляйтесь на React 18.
• Suspense с fallback={undefined} теперь эквивалентен fallback={null}. Ранее undefined позволял «перескочить» границу; теперь ноль-значение учитывается как пустой fallback.

Серверная отрисовка (Server Side Rendering, SSR)

React 18 добавил новые серверные API и стриминг.

Краткое определение: SSR — выполнение рендеринга React на сервере, отправка готового HTML клиенту.

Клиентская часть:

Замените ReactDOM.hydrate() на hydrateRoot() из react-dom/client.

// Before

import App from “./App.js”;

import ReactDOM from “react-dom”;

const container = document.getElementById(“react”);

ReactDOM.hydrate(, container);

// After

import App from “./App.js”;

import {createRoot} from “react-dom/client”;

const container = document.getElementById(“react”);

const root = hydrateRoot(container, );

Серверная часть:

Замените renderToNodeStream() на renderToReadableStream(), где это актуально. Новая модель стриминга даёт возможность серверу продолжать отправлять HTML после первого рендера приложения, поддерживая Suspense на стороне сервера и улучшая время до интерактивности.

Примечание: реорганизация SSR требует тестирования. Проверьте, что сервер корректно формирует поток и что клиентская гидратация согласована с серверной разметкой.

Начало использования возможностей React 18

После миграции вы сможете начать пользоваться новыми фичами:

• Конкурентная отрисовка — React может приостанавливать и возобновлять рендер для улучшения отзывчивости.
• Suspense: расширены возможности, в том числе серверный Suspense.
• Transitions: API для маркировки обновлений с низким приоритетом (например, переключение страниц без блокировки интерфейса).
• Встроенные механизмы для троттлинга частых неважных обновлений.
• Дополнительные HTML-атрибуты: imageSizes, imageSrcSet, aria-description и др.

Короткое описание Transitions: метод startTransition позволяет пометить обновления как не срочные. Это помогает удерживать главный поток интерактивным.

Пример использования Transitions (синтаксис кратко):

• Оберните пользовательское действие в startTransition().
• Внутри обновления устанавливайте состояние, которое может быть отложено без потери UX.

Подробный поэтапный план миграции (микро‑методология)

Ниже — практический чеклист для поэтапной миграции крупных проектов.

1. Линкайте изменения в ветке feature/upgrade-react-18.
2. Обновите зависимости (react, react-dom).
3. Запустите тесты и линтеры — исправьте базовые ошибки.
4. Замените точки входа: ReactDOM.render -> createRoot, ReactDOM.hydrate -> hydrateRoot.
5. Прогоните приложение в режиме разработки, исправьте предупреждения.
6. Протестируйте все критичные страницы и взаимодействия вручную.
7. Проверьте компоненты, использующие refs, сторонние библиотеки, контексты.
8. Прогоните интеграционные тесты и E2E.
9. Включите возможности Gradual Enablement (активируйте в стейдже, затем в проде).
10. Мониторьте метрики отзывчивости и ошибок после релиза.

Этот мини‑процесс даёт управляемый и обратимый план внедрения.

Ролевые контрольные списки

Разделите задачи между ролями — разработчик, тестировщик, DevOps.

Разработчик:

• Обновил пакеты и заменил точки входа.
• Проверил использование устаревших API (unstable_*).
• Изменил места с render-callbacks на refs/эффекты.
• Протестировал поведение при double-mount в Strict Mode.

Тестировщик (QA):

• Прогнал сценарии E2E для ключевых пользовательских потоков.
• Проверил производительность и время до интерактивности.
• Оценил поведение при плохом соединении (SSR + streaming).

DevOps:

• Обновил CI/CD конфигурацию (npm install).
• Проверил совместимость сборщика (webpack/vite) с React 18.
• Настроил пошаговый откат (rollback) на случай регрессий.

Частые проблемы и как их решать

• Проблема: неожиданное поведение при setState в промисах или таймаутах. Решение: пересмотрите логику, используйте функциональные обновления или flushSync, если нужно форс‑применение.

• Проблема: сторонняя библиотека использует устаревшие internals. Решение: обновите библиотеку или замените на поддерживаемую. Временно зафиксируйте её версию и откладывайте миграцию на тестовой ветке.

• Проблема: SSR-потоки расходятся с клиентской гидрацией. Решение: убедитесь, что серверный рендер и клиентовый код используют одинаковые props, и что вы применяете hydrateRoot для гидрации.

Когда не стоит мигрировать сейчас (контрпример)

• Если ваш продукт обязан поддерживать Internet Explorer — React 18 не подходит.
• Если у вас множество нативных интеграций, ожидающих точного порядка побочных эффектов, и вы не можете быстро рефакторить — отложите миграцию.
• Если вы полагаетесь на render-callbacks во многих местах и рефакторинг займёт слишком много времени.

В таких случаях спланируйте миграцию, но выполните её поэтапно или используйте feature‑флаги.

Ментальные модели и эвристики

• «Root как управляющий объект»: думайте о createRoot как о менеджере жизненного цикла, а не одноразовой функции.
• «Автоматический батчинг — ожидаемое поведение»: не полагайтесь на немедленное наблюдение за промежуточным состоянием.
• «Strict Mode — страховочная сетка»: баги, выявленные Strict Mode, помогут подготовиться к будущим улучшениям React.

Эти простые модели помогут принимать решения при рефакторинге.

Матрица совместимости и заметки по миграции

• React 17 -> React 18: прямой апгрейд возможен, но требует проверки render points.
• Библиотеки: большинство популярных библиотек обновились; проверьте поддержку у провайдеров UI-компонентов.
• Бандлеры: Webpack, Vite, Parcel поддерживают React 18; проверьте плагины и лоадеры.
• Browserslist: обновите конфигурацию, если вам не нужны старые полифиллы.

Риск‑матрица и меры смягчения (qualitative)

• Риск: регрессии в UI после батчинга — Средний. Митигация: тесты, flushSync в критичных местах.
• Риск: поломка сторонних библиотек — Средний/Высокий. Митигация: обновление зависимостей, замена библиотек.
• Риск: проблемы с SSR-гидрацией — Средний. Митигация: интеграционные тесты, контроль версий серверного рендера.

Критерии приёмки

1. Приложение собирается без ошибок.
2. Все E2E тесты выполняются успешно.
3. Критичные пользовательские сценарии работают и имеют приемлемое время до интерактивности.
4. Нет неожиданных предупреждений в продакшн-логах.

План отката и runbook при инциденте

1. При серьёзной регрессии откатите деплой до предыдущей рабочей сборки.
2. Создайте горячую фиксацию в feature-ветке, реплицируйте проблему локально.
3. Если проблема связана с автоматическим батчингом, временно используйте flushSync в местах, где это критично.
4. Проанализируйте логи, проведите bisect по коммитам, верните обновления поэтапно.

Полезные снэпшоты/шаблоны

Пример простого playbook для миграции (короткая шпаргалка):

• git checkout -b upgrade/react-18
• npm install react@latest react-dom@latest
• заменить ReactDOM.render() -> createRoot
• заменить ReactDOM.hydrate() -> hydrateRoot
• пройти unit/integration/E2E тесты
• деплой в staging, smoke tests
• мониторить метрики и ошибки

Социальный анонс и краткое сообщение

Короткое объявление (100–200 слов):

Мы обновили приложение до React 18. Обновление включает новый Root API, улучшенную поддержку Suspense и серверный стриминг. Это повышает гибкость и отзывчивость интерфейса. Основные шаги миграции: обновление npm-пакетов, замена точек входа на createRoot/hydrateRoot и тестирование в Strict Mode. Постепенный rollout и мониторинг метрик сводят риски к минимуму.

Превью для соцсетей

OG title: Обновление на React 18 — что нужно знать OG description: Пошаговое руководство по переходу на React 18, новый Root API, SSR‑стриминг и практические советы по миграции.

Краткая сводка

React 18 готов к использованию. Большинство проектов обновятся быстро: достаточно npm-апдейта и замены точек входа. Однако уделите внимание Strict Mode, автоматическому батчингу и SSR-изменениям. Для крупных проектов используйте поэтапный план и ролевые чеклисты.

Ресурсы и ссылки

• Официальная документация React (посетите reactjs.org для подробностей).
• Руководства по SSR и примеры использования hydrateRoot и renderToReadableStream.

Примечание

• Не забудьте проверить сторонние библиотеки на предмет поддержки React 18 перед обновлением в продакшен.

Сводка ключевых выводов

• Обновление чаще всего просто, но требует проверки.
• Новый Root API обязателен для включения фич React 18.
• Автоматический батчинг и Strict Mode могут выявить проблемы, требующие рефакторинга.
• Для SSR используйте новые stream API и hydrateRoot.

Короткая памятка: начните с ветки, обновите зависимости, поменяйте точки входа и прогоните тесты. Миграция пройдёт гладко при поэтапном и контролируемом подходе.