Как разделить большое React‑приложение: границы пакетов и владение маршрутами

Почему одно React‑приложение начинает тормозить команды

React‑приложение само по себе не замедляет команду только потому, что стало большим. Некоторые крупные приложения продолжают быстро развиваться. Настоящая проблема появляется, когда никто не может сказать: «эта часть принадлежит этой команде и изменения здесь заканчиваются».

Папки с общим кодом обычно создают первую путаницу. Директория components или utils начинается как удобное место для общих сущностей, а потом превращается в кладовку. Люди добавляют полупереносимые хуки, одноразовые хелперы, куски лэйаута и скопированные паттерны. Через несколько месяцев никто уже не знает, что безопасно менять, и каждая правка кажется рискованной.

Тогда даже небольшие UI‑задачи растягиваются дальше, чем нужно. Замена кнопки оплаты может потребовать правок в общем компоненте формы, хелпере валидации, обёртке маршрута, файле feature‑флага и настройке тестов, которые используются в трёх других областях. Код может и работать, но стоимость простой правки растёт.

Болевые точки команд появляются задолго до полного краха приложения. Конфликты слияния увеличиваются, потому что несколько человек меняют одни и те же общие файлы. Ревью замедляются, потому что ревьюерам нужен контекст из частей приложения, которыми они не владеют. Релизы становятся напряжёнными, потому что безобидная правка в общем пакете может одновременно повлиять на страницы аккаунта, отчёты и админку.

Именно поэтому команды обычно решают разделить большое React‑приложение. Давление исходит от вопросов владения и привычек релизов, а не от количества файлов. Грязное приложение на 40 экранов может причинять больше бед, чем хорошо структурированное на 400.

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

Почему микрофронтенды часто — неправильный первый шаг

Микрофронтенды могут решить реальную проблему, но приносят и новые. Вы разделяете не только код: вы разделяете поведение в рантайме, правила деплоя, общий UI и часть внимания команды.

Обычное разделение React‑проекта чаще всего означает пакеты, границы маршрутов и более чёткое владение внутри одного приложения. Это сохраняет один роутер, одну дизайн‑систему, один поток авторизации и один путь релиза. Настройка микрофронтендов добавляет уровни сверху: app shells, удалённую подгрузку, сопоставление версий, правила кросс‑приложного состояния и больше способов, как одна команда может сломать экран другой.

Маршрутизация обычно осложняется первой. В одном приложении можно просто задать правила вроде billing владеет /billing и reports владеет /reports. С микрофронтендами команды начинают спорить о навигации, редиректах, лэйауте и контроле общих областей вроде шапки или меню аккаунта.

Состояние тоже быстро становится грязным. Если пользователь входит в систему, меняет организацию или обновляет настройки, каждая часть приложения должна получать одно и то же состояние. В пределах одного деплойного приложения это скучно и предсказуемо. Через несколько рантаймов общее состояние часто превращается в кастомные события, дублированные кэши или неловкие перезагрузки.

Тихая цена — «дрейф дизайна». Одна кнопка становится тремя версиями. Ошибки форм выглядят по‑разному на разных страницах. Мелкие различия накапливаются, и продукт начинает ощущаться сшитым из кусков.

Одно деплойное приложение всё ещё имеет смысл, когда команды работают над разными маршрутами, но у них общие пользователи, навигация, аутентификация, дизайн‑система и правила данных. Это также удобно, когда релизы происходят часто и команды могут координироваться в одном пайплайне. В таком случае проблема — владение, а не изоляция на уровне браузера.

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

Обрисуйте границы пакетов вокруг реальной работы

Чистое разделение начинается с того, как люди работают, а не с того, как выглядят папки. Если одна команда владеет биллингом, дайте биллингу собственный пакет. Поместите туда экраны, вызовы API, правила форм и тесты для биллинга. Новый разработчик должен открыть папку и увидеть полноценный срез продукта, а не разбросанные по проекту components, hooks и utils.

Группировка по типу файлов кажется аккуратной месяц‑два. Потом каждая фича затрагивает шесть папок, и простые изменения превращаются в поиски по всему репо. Пакеты, сгруппированные по областям продукта, сокращают этот шум. Они также упрощают код‑ревью, потому что большинство изменений остаётся в рамках одной области.

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

Например, пакет биллинга может включать экраны счетов, страницы методов оплаты, запросы к биллинговым эндпоинтам, правила форматирования, используемые только в биллинге, и тесты сценариев биллинга. Это полноценный срез работы, и его гораздо проще понять.

Выносите код наружу только тогда, когда две области действительно используют его и используют одинаково. «Возможно, нам это пригодится позже» — плохая причина создавать общий пакет. Большинство ранних общих папок становятся кладовками. Подождите повторного использования, затем извлеките минимальную вещь, которая реально убирает дублирование.

Имена пакетов должны быть скучными и очевидными. @app/billing, @app/account и @app/reports лучше, чем расплывчатые @app/core или @app/common. Если имя скрывает владение, люди будут продолжать кидать туда случайный код.

Здесь и начинается реальная отдача. Хорошие границы пакетов снижают шум в ревью, уменьшают случайную связанность и упрощают поддержание правил владения в будущем.

Назначьте каждому маршруту чёткого владельца

Большие React‑приложения превращаются в кашу, когда много людей могут менять один и тот же маршрут, и никто не чувствует за него ответственности. Маршрут нужен владелец так же, как и область продукта.

Дайте каждому ключевому маршруту одну команду или одного человека, который может сказать «да», «нет» или «не сейчас». Этот владелец не обязан сам делать каждое изменение, но должен иметь последнее слово о том, как маршрут работает, что туда входит и что стоит вынести в общий пакет.

Это работает лучше, когда владелец контролирует локальные решения: местные компоненты, форму локального состояния, поток загрузки данных и тесты уровня маршрута. Если другая команда хочет повторно использовать что‑то, по умолчанию должен оставаться простой ответ: выносите в общий пакет только если более чем один маршрут действительно этого требует.

Запишите границу в коротком наборе правил. Другие маршруты должны импортировать только публичные части. Публичные части должны жить в явном файле экспорта. Приватные хуки, хелперы и компоненты остаются внутри маршрута. Если два маршрута нуждаются в общем состоянии, создайте согласованный общий пакет вместо прямых заходов в файлы друг друга.

Это важнее, чем кажется. Команды обычно ломают границы, импортируя внутренности другого маршрута, потому что так кажется быстрее. Быстрый импорт из другого маршрута может создать месяцы скрытой связанности. Тогда небольшая рефакторинг в /settings ломает /checkout без видимой причины.

Владение также избавляет маршруты‑сироты от «гниения». Старые админские экраны, страницы миграций и забытые представления отчётов часто живут долго после того, как исходная команда ушла. Пересматривайте такие маршруты по расписанию. Если у маршрута нет владельца — назначьте его, войдите в другую область или удалите.

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

Разделяйте приложение малыми шагами

Крупные переписывания обычно терпят неудачу, потому что команды одновременно меняют структуру, владение и привычки релизов. Лучше картировать приложение таким, какое оно есть сегодня. Запишите каждый маршрут, кто чаще всего его меняет, какой код он разделяет с другими и где релизы тормозят, потому что одна правка затрагивает слишком много файлов.

Начните с одного маршрута, который кажется загромождённым и активным, а не с самого трудного. Может быть, биллинг меняется каждую неделю, а отчёты почти никто не трогает. Перенесите биллинг в отдельный пакет первым и держите приложение в рабочем состоянии всё время. Первый шаг даст команде больше опыта, чем две недели планирования.

Начните с одного маршрута

Держите границу тонкой и очевидной. Поместите экраны маршрута, хуки, тесты и локальные компоненты внутрь пакета. Оставьте по‑настоящему общий UI в общем пакете, но будьте строгими. Если хелпер существует только для биллинга — держите его в биллинге.

Затем запретите новые импорты между маршрутами. Старые импорты можно оставлять на короткое время, пока вы их не почистите, но новые создают новый технический долг. Линт‑правило или проверка импортов в CI будет достаточно. Цель проста: пока команда закрывает старые утечки границ, никто не добавляет новые.

Добавьте маленькие API между пакетами

Команды творят беспорядок, когда один маршрут глубоко залезает в файлы другого. Так делать нельзя. Экспортируйте маленькое API из каждого пакета, например компонент, хук или типизированную функцию. Account может запросить у billing «get billing summary». Account не должен импортировать пять внутренних файлов биллинга только потому, что так работает сейчас.

Простой паттерн: один пакет — одна фича/маршрут, один публичный entry‑файл на пакет, один владелец для изменений, которые пересекают границу, и одна короткая заметка о релизе при изменении публичного API.

После первого маршрута повторите процесс с следующим наиболее загруженным участком. Не ждите идеального дизайна. К третьему переносу команда обычно видит, какой код действительно общий, а что было общим только потому, что его было легко позаимствовать.

Используйте дисциплину релизов, чтобы поддерживать границы

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

Если хотите сохранить здоровье разделения, относитесь к обновлениям пакетов как к небольшим продуктовым релизам. Дайте каждому общему пакету понятную версию. Пишите короткие заметки для каждого релиза: что поменялось, какие маршруты могут это почувствовать и безопасное/рискованное/ломающее ли это изменение.

Рискованные рефакторы требуют своего окна. Не мержьте переименование общих хуков, контрактов маршрутов или токенов дизайна за день до релиза. Сначала выпускайте пользовательский функционал. Перенесите глубокую очистку в отдельный батч, когда у команд будет время протестировать и исправить последствия без паники.

Одна группа должна одобрять любое изменение, пересекающее границу. Это может быть платформа, владелец архитектуры или старший инженер по ротации. Правило важнее титула. Если account хочет залезть в биллинговые внутренности, кто‑то должен остановить это до мержа.

Сам рутин релизов может оставаться простым. Публикуйте общие пакеты с понятной версией и короткими заметками. Тестируйте затронутые маршруты до обновления, применяйте изменение и снова тестируйте те же маршруты после. Храните шаги отката в репозитории и делайте их достаточно короткими, чтобы следовать им в стрессовой ситуации.

Записанные шаги отката экономят время, когда что‑то прошло мимо. «Вернуть пакет X на 2.3.1, деплойнуть маршрут Y, очистить кэшированный бандл» гораздо полезнее, чем смутный план в чате.

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

Простой пример с account, billing и reports

Представьте кодовую базу React с одной большой папкой src. Экраны аккаунта, формы биллинга, виджеты отчётов, хуки, API‑запросы и общий UI живут рядом. Такое устройство какое‑то время работает, а потом каждая правка начинает походить на трогание связки оголённых проводов.

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

Этот пакет не должен поглощать всё, что касается него. Поддерживаемые кнопки, поля форм и базовые лэйауты держите в отдельном общем пакете. Пакет account должен содержать работу по account, а не превращаться во вторую кладовку.

Биллинг чаще всего идёт следующим, потому что ошибки там обходятся дорого и подрывают доверие. Дайте биллингу отдельную область маршрутов и пакет: checkout, invoices, methods of payment и billing settings — всё за этой границей. Если изменение влияет на начисления, владелец биллинга его проверяет. Строгость этого правила оправданна.

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

Когда account и billing получают чётких владельцев, релизы обычно быстро успокаиваются. Обновление профиля не тянет за собой ревью биллинга. Изменение оплаты не случайно не уходит вместе с правками отчётов. Люди знают, кто что утверждает, какие тесты важны и какие пакеты можно менять без длительных межкомандных переписок.

Именно этого команды часто не замечают. Границы пакетов помогают, но ещё больший выигрыш — ясное владение. Когда account, billing и reports перестают казаться «общими для всех», они и перестают ломаться «для всех».

Ошибки, которые превращают разделение в новую путаницу

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

Обычная ошибка — фиктивный shared‑пакет. Маршрут имеет один хелпер, один хук или один компонент формы, и кто‑то выносит это в shared, потому что «может пригодиться позже». Если эту штуку использует только биллинг, держите её в биллинге. Общий пакет должен решать повторяющуюся проблему. Иначе он превращается в кладовку, к которой прикасаются все, но никто не владеет.

Ещё одна проблема — маршруты, лезущие во внутренности друг друга. Reports импортирует хук из billing. Account читает состояние биллинга напрямую. В моменте кажется быстрее, но это создаёт скрытые связи между командами. Малый рефактор в одной области ломает другую, которая должна была остаться отдельной. Если маршрут нуждается в чём‑то другого — экспортируйте небольшое публичное API и остановитесь на этом.

Ежеспринтовое изменение границ создаёт другой хаос. Команды не успевают привыкнуть к структуре, тесты постоянно перемещаются, владение остаётся расплывчатым. Границы не обязаны быть идеальными с первого дня, но им нужна стабильность. Перемещайте код только когда текущий расклад реально вызывает боль, а не потому, что новая идея папок кажется чище.

Правила релизов тоже важны. Если одна команда выкатывает каждый день, а другая ждёт ручной релиз, общие изменения копятся и блокируют друг друга. Это трение выглядит как кодовая проблема, хотя причина — расписание. Выберите один простой ритм релизов и одно правило версионирования для всех.

Начинать с module federation до установления базового владения — одна из самых дорогих ошибок. Дополнительные рантайм‑слои не исправляют размытые границы пакетов. Они лишь делают сломанные границы труднее увидеть и отлаживать.

Здоровое разделение обычно выглядит скучно. Каждый маршрут владеет своим кодом. Общие пакеты остаются небольшими. Маршруты импортируют публичные API, а не внутренности. Команды соблюдают единые правила релизов. Рантайм остаётся простым, пока команда не докажет необходимость усложнений.

Быстрые проверки перед тем, как считать работу завершённой

Разделённое приложение может выглядеть чистым на доске, но всё ещё быть грязным в ежедневной работе. Когда структура работает, большая часть задач остаётся локальной. Одна команда меняет одну область, выпускает её и может откатить без втягивания трёх других команд.

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

• Есть ли у каждого маршрута один ясный владелец?
• Экспортирует ли каждый пакет небольшой публичный входной файл?
• Общий код всё ещё редкость, или shared растёт каждую неделю?
• Могут ли команды выпускать изменения маршрутов, не затрагивая чужие маршруты?
• Может ли кто‑то выполнить шаги отката без длинного созвона?

Практический тест лучше большинства архитектурных дебатов. Откройте последние пять pull request‑ов и посмотрите, что менялось. Если работа по reports постоянно трогает внутренности billing, или изменения в account редактируют shared‑код, значит пакеты, скорее всего, разделены по папкам, а не по ответственности.

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

Что делать дальше

Если вы хотите разделить большое React‑приложение, начните с карты, а не с переписывания. Большинство команд уже знают, где боль: в медленных ревью, неясном владении и релизах, которые затрагивают слишком много файлов.

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

Потом выберите один маршрут с понятной бизнес‑ценностью для первого разделения. Пропишите два‑три правила импортов и примените их через линт и код‑ревью. Проверьте, как вы сейчас релизите изменения, прежде чем добавлять рантайм‑слои, которые усложнят видимость существующих проблем.

Держите первый перенос скучным. Выберите маршрут вроде billing, reports или account settings. Перенесите экраны, состояние, тесты и локальные хелперы в один пакет. Затем посмотрите, что ломается. Вы научитесь больше от одного аккуратного разделения, чем от месяца архитектурных споров.

Привычки релизов требуют такого же внимания. Если одна правка всё ещё требует одобрения трёх команд, структура ещё недостаточна. Ужесточите версионирование, пересмотрите, кто может менять общие пакеты, и сделайте владельцев маршрутов ответственными за выпуск своей области.

Если хотите второе мнение, Oleg Sotnikov at oleg.is работает как Fractional CTO со стартапами и малыми командами по границам пакетов, владению маршрутами, потоку релизов и практическим настройкам инженерии с акцентом на AI‑решения. Внешний обзор может помочь до того, как вы добавите больше сложности в рантайме.