Improved FSD: как структурировать React-проект строже, чем классический Feature-Sliced Design
Текст написан с позиции марта 2022 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Когда React-проект растет, почти любая команда рано или поздно упирается в один и тот же предел: код работает, фичи поставляются, но внутренняя структура начинает сопротивляться развитию. Новые модули сложно размещать, зависимости расползаются, страницы начинают знать слишком много о сторе, UI-компоненты подтягивают бизнес-логику, а попытки «просто чуть-чуть переиспользовать» быстро превращаются в неявные связи между далекими частями приложения. На этом фоне закономерно усилился интерес к архитектурным подходам, которые позволяют держать фронтенд в порядке дольше, чем первые несколько месяцев активной разработки.
Одним из самых заметных направлений в последнее время стал Feature-Sliced Design. Идея разрезать приложение по смысловым слоям и фичам оказалась очень полезной: кодовая база становится понятнее, повторное использование — осмысленнее, а границы между ответственностями — заметнее. Но на практике во многих командах довольно быстро выясняется, что классическая схема FSD все равно оставляет слишком много свободы. Формально структура есть, но на больших проектах этого недостаточно. Разработчики начинают по-разному трактовать границы слайсов, часть логики уходит в общие директории, между слоями появляются неочевидные мосты, а архитектурные правила приходится держать в голове, а не считывать из дерева проекта.
Именно в этот момент возникает естественное желание сделать подход строже. Не отказаться от идей FSD, а усилить их. Важно не свалиться в другую крайность и не воспринять это как «давайте напишем много правил»: речь не о бюрократии, а о том, чтобы сделать структуру более принудительной, зависимости — более очевидными, а нарушение уровней — более заметным уже на уровне папок.
Почему классического FSD часто недостаточно
Feature-Sliced Design хорошо работает как мыслительная модель. Он помогает отделять прикладной уровень от доменного, отделять интерфейсные сущности от инфраструктуры и бороться с бесформенным хаосом в папках. Но чем крупнее React-приложение, тем сильнее становится спрос не просто на рекомендации, а на более жесткую систему координат. На уровне концепции FSD может говорить: «страницы не должны знать лишнего», «фичи должны быть изолированы», «shared должен оставаться общим». Однако в реальной кодовой базе эти принципы часто размываются.
Самая вредная реакция на это — решить, что «FSD не работает» и вернуться к свободной раскладке по папкам. Вывод неверный. Проблема не в самом подходе, а в широте трактовок. Что считать фичей, а что виджетом? Где заканчивается страница и начинается orchestration-логика? Куда выносить сложные эффекты, которые объединяют несколько независимых частей состояния? Где жить табличным модулям, попапам, редакторам, фильтрам и другим крупным сборкам, которые уже не просто UI, но еще и не страница? Чем дольше проект живет, тем чаще эти вопросы решаются ситуативно. В результате внутри команды появляются разные локальные архитектуры под одной общей вывеской.
Строгая интерпретация improved FSD решает эту проблему за счет того, что не оставляет слишком много промежуточных состояний. Вместо набора обобщенных уровней проект получает конкретные этажи с понятной ролью. Каждый этаж может зависеть только вниз. Нижележащие части не могут тянуть вверх ничего. Именно это и дает два главных преимущества: четкую структуру и естественное предотвращение циклических зависимостей.
Главная идея improved FSD
В основе этого варианта лежит очень простой и сильный принцип: дерево директорий должно быть не просто способом разложить файлы, а отражением направленного графа зависимостей. Чем выше уровень, тем больше он знает о приложении в целом. Чем ниже уровень, тем он проще, универсальнее и стабильнее. Нижние уровни не знают о верхних. Значит, у нас появляется почти физическое ощущение направления архитектуры: от базовых инструментов и данных к модулям, фасадам, поведению и конечной сборке приложения.
Если сформулировать совсем коротко, то improved FSD — это React-архитектура, где папки не просто группируют код, а принуждают разработчика думать слоями. Это особенно полезно для команд, где проект развивается быстро, а стоимость разрастания связей очень высока. В такой схеме разработчик, открыв дерево проекта, уже видит не только «где что лежит», но и «что от чего имеет право зависеть».
Структура выглядит так:
app behavior facades modules packages tools types utilsНа первый взгляд набор необычный, особенно если сравнивать его с учебными примерами FSD. Но именно в этом и ценность. Почему отступление от канонических названий здесь оправдано? Потому что архитектура подогнана не под теоретически красивые названия, а под реальные роли кода внутри React-приложения.
Общий принцип зависимостей
Перед тем как разбирать каждую директорию отдельно, важно зафиксировать главное правило: зависимость может идти только вниз по уровню. Верхние слои собирают нижние, но нижние не должны знать о верхних. Это значит, что facades могут использовать modules, packages, tools, utils и types, но не наоборот. modules могут собираться из packages, tools, utils и types, но не должны импортировать facades или behavior. И так далее.
Это ограничение ценно сразу по нескольким причинам. Во-первых, оно делает поток знаний односторонним. Во-вторых, оно естественно разрывает возможность циклов: если нижний слой не может тянуть верхний, граф становится направленным. В-третьих, такая схема упрощает рефакторинг: можно безопаснее переписывать крупные уровни, не опасаясь, что внизу на них незаметно завязано полпроекта.
Для современных React-проектов это особенно актуально. Приложения уже достаточно сложны, чтобы архитектурная нестрогость дорого обходилась, но экосистема все еще оставляет разработчику много свободы, а значит и много способов случайно испортить границы. И вот тут возникает соблазн наивной реакции: «у нас же есть линтер, он поймает». Не поймает. Линтер видит синтаксис, но не видит замысла слоев — пока сами слои размыты, нарушать их можно сколько угодно, не споткнувшись ни об одно правило.
app — сборка приложения и базовая верстка
Директория app — это верхняя точка приложения. Здесь живет сборка всего дерева, корневые маршруты, композиция крупных экранов, базовые layout-решения и то, что можно назвать каркасом интерфейса. Это не место для глубокой предметной логики и не склад reusable-компонентов. Это точка, где приложение собирается в единое целое.
В React-проекте сюда логично относить инициализацию корневого компонента, общие провайдеры, тему, подключение роутинга, оболочки страниц, базовые контейнеры и начальный wiring. Важный момент: app не должно разрастаться до уровня «здесь лежит все самое важное». Его задача именно в orchestration верхнего уровня, а не в хранении всей логики проекта.
С архитектурной точки зрения app удобно тем, что он уже по названию сигнализирует: это верхушка, сюда можно тянуть многое, но отсюда не должно утекать знание вниз. Если какой-то нижний уровень начинает импортировать что-то из app, это почти наверняка ошибка проектирования.
behavior — уровень поведений и сложных эффектов
Один из самых интересных уровней в этой схеме — behavior. Именно он отличает improved FSD от более типовых структур. Здесь живут поведения, объединяющие сложные структуры эффектов. Это очень важное уточнение. Во многих проектах именно эта логика создает наибольший архитектурный шум, потому что она уже не UI, но еще и не просто данные. Это orchestration-поведение, которое может связывать несколько источников состояния, сетевые процессы, сценарии взаимодействия и реакцию интерфейса на внешние события.
Если такого уровня нет, подобный код обычно расползается по страницам, хукам, сервисам, сторам или случайным директориям вроде helpers и lib. В итоге сложное поведение оказывается размазанным по проекту, а повторное использование становится болезненным. Выделение behavior как отдельного уровня говорит команде: многосоставная прикладная логика, объединяющая эффекты, — это самостоятельная сущность архитектуры.
Например, если в системе есть сценарий, где изменение фильтров должно обновлять таблицу, сбрасывать пагинацию, инициировать загрузку, синхронизировать часть состояния с URL и запускать дополнительные побочные действия, такой код не должен растворяться в странице. Это именно поведение. Оно может использовать низкоуровневые структуры, но само должно оставаться высокоуровневым слоем.
facades — большие страницы и крупные экранные сборки
Уровень facades отвечает за большие страницы. Это удачное название, потому что оно подчеркивает характер ответственности: фасад собирает внутренние части в цельный внешний экран. В нем не обязано жить все содержимое страницы построчно, но именно здесь находится публичная экранная форма крупного участка интерфейса.
Почему не просто pages? Потому что слово facades чуть лучше передает идею композиции. Такой слой не обязательно равен роуту один к одному. Это может быть и большой самостоятельный экран, и сложная надстройка над несколькими модулями, и крупная прикладная сборка, показывающая пользователю цельный сценарий.
Facades зависят от modules, packages, tools, utilsи types, но не от behavior: поведенческий уровень стоит выше и сам опирается на фасады. Но и сами фасады не должны становиться свалкой инфраструктурных деталей. Их задача — выразить большой интерфейсный сценарий, а не заменить собой всю архитектуру.
На практике это очень полезно для React-страниц, которые в обычных проектах часто вырастают в гигантские файлы на несколько сотен строк. Выделение фасадов позволяет оставить странице роль композиции, а не контейнера для всего подряд.
modules — таблицы, попапы и другие крупные интерфейсные блоки
Modules в этой схеме — это важный рабочий слой. Сюда попадают таблицы, попапы, фильтры, формы, редакторы, панели и другие крупные UI-блоки, которые уже обладают собственной внутренней логикой и прикладной ценностью, но еще не являются целой страницей. Для больших React-приложений это один из самых востребованных уровней, потому что именно такие сущности чаще всего переиспользуются между экранами.
Ключевое достоинство выделения modules в отдельную директорию в том, что оно помогает не путать крупные прикладные блоки с базовыми компонентами. В обычной структуре таблица со сложной сортировкой, загрузкой, фильтрацией и взаимодействием с данными нередко оказывается либо в components, либо прямо внутри страницы. Оба варианта плохи. В первом случае теряется различие между кнопкой и огромным интерактивным блоком. Во втором — переиспользование становится дорогим.
В improved FSD модуль — это самостоятельная архитектурная единица. Он может использовать packages для данных и стора, tools для UI-основы, utils для хелперов и types для контрактов, но не должен знать про фасады и страницы. Благодаря этому модуль остается переносимым и не заражается контекстом конкретного экрана.
packages — стор, данные и загрузка
Директория packages отвечает за стор, данные и загрузку. Это слой, где живет то, что можно назвать прикладной инфраструктурой данных. Здесь могут располагаться хранилища состояния, сущности загрузки, API-обертки, нормализаторы ответов, репозитории, адаптеры или иные структуры, обслуживающие поток данных в приложении.
Выбор названия packages тоже показателен. Он как бы отделяет этот уровень от UI и подсказывает, что здесь лежат более «собранные» единицы логики. Это не просто отдельные функции, а относительно законченные блоки работы с данными и состоянием. Для React-архитектуры это вполне практичный компромисс: слой уже выше чистых утилит, но еще ниже модулей и экранов.
Очень важно, что packages не должны знать о визуальных сценариях. Стор не должен импортировать попап, загрузчик данных не должен зависеть от страницы, а сущность работы с API не должна тянуть верстку. Благодаря этому слой данных остается стабильнее, а его повторное использование становится естественным.
tools — базовые компоненты
Tools — это уровень базовых компонентов. Здесь лежат строительные кирпичи интерфейса: кнопки, поля ввода, контейнеры, типовые панели, базовые элементы управления, примитивные layout-объекты и прочие reusable-компоненты, которые не должны знать о конкретной предметной области.
Почему не назвать этот слой просто ui или components? Потому что слово tools неплохо подчеркивает инструментальный характер этих сущностей. Они помогают строить модули и фасады, но сами не выражают конкретный бизнес-сценарий. Это полезное семантическое ограничение. Как только разработчик пытается положить сюда что-то слишком предметное, само название начинает сопротивляться.
В большом React-проекте это особенно важно, потому что папка components почти всегда рано или поздно превращается в бесполезную корзину всего подряд. Tools работает как более точное слово: сюда попадает то, чем пользуются другие слои для сборки интерфейса, но не то, что уже стало самостоятельной прикладной частью.
utils — хелперы и мелкие обработчики данных
Уровень utils знаком любой команде, но именно поэтому особенно опасен. Если не ограничивать его смысл, он очень быстро превращается в архитектурный черный ящик. В improved FSD этот слой должен быть максимально приземленным: функции-хелперы, простые преобразования, небольшие обработчики данных, форматирование, примитивная вспомогательная логика без сильной предметной связности.
Главное правило для utils — не превращать его в скрытый сервисный слой. Если функция начинает знать слишком много о бизнес-процессе, сторе, структуре модуля или сценарии страницы, ей уже не место в утилитах. Иначе слой, который должен быть самым низким и безопасным, станет каналом утечки доменного контекста по всему проекту.
Когда utils остаются маленькими и чистыми, они действительно полезны. Они упрощают код, снижают дублирование и не создают высоких архитектурных рисков. Но как только в утилиты начинают прятать серьезную прикладную логику, вся строгость слоев постепенно ломается.
types — общие типы и контракты
Отдельно стоит проговорить роль types: наличие этой директории в структуре очень логично. Для TypeScript-проекта общий слой типов — это удобный способ вынести контракты, интерфейсы, общие модели и структурные соглашения, которые нужны сразу нескольким уровням.
Но и здесь нужна дисциплина. Types не должны становиться обходным каналом зависимости. Если типы начинают тянуть за собой runtime-логику или слишком предметные связки между высокими слоями, архитектурная чистота исчезает. Общие типы полезны, пока они действительно описывают форму данных, а не маскируют coupling между частями приложения.
Как эта схема предотвращает циклические зависимости
Одна из самых сильных сторон improved FSD — естественная защита от циклов. В обычном React-проекте циклы чаще всего появляются там, где слои определены расплывчато. Страница импортирует модуль, модуль тянет helper из shared, helper внезапно знает о сторе страницы, а стор в какой-то момент импортирует константу из той же страницы или модуля. Такие связи могут быть неочевидны, но со временем они образуют сложную сеть обратных зависимостей.
В этой схеме такое сильно затруднено из-за самого устройства уровней. Если нижележащие не могут зависеть от вышележащих, граф направлен сверху вниз. Значит, чтобы получить цикл, нужно явно нарушить архитектурное правило. А это уже намного лучше, чем архитектура, в которой цикл возникает почти случайно и обнаруживается слишком поздно.
Именно поэтому подобная структура хорошо сочетается с автоматическими проверками импортов, линт-ограничениями и правилами ревью. Архитектура становится не только понятной, но и проверяемой.
Почему четкая структура особенно важна для React
React сам по себе не навязывает жесткую архитектуру приложения. Он дает модель компонентного интерфейса, но не решает за команду, где должны жить данные, как делить поведение, что считать модулем, а что страницей. Это одновременно сила и слабость. Небольшие проекты выигрывают от гибкости, но большие кодовые базы платят за нее очень быстро.
Сегодня React-проекты уже редко ограничиваются набором простых экранов. Даже среднее приложение обычно содержит формы, таблицы, фильтрацию, авторизацию, асинхронную загрузку, локальное и глобальное состояние, маршруты, переиспользуемые блоки и массу промежуточной логики. Без строгой структуры все это быстро смешивается. Поэтому improved FSD стоит понимать не как стилевую прихоть, а как попытку дать React-проекту более жесткий позвоночник, не отказываясь от компонентного подхода.
Пример потока сборки снизу вверх
Хорошо понять эту архитектуру помогает мысленный поток сборки. Внизу у нас находятся utils, types и tools. Это самые базовые части. Выше — packages, которые обеспечивают данные, стор и загрузку. Еще выше — modules, где из базовых компонентов и источников данных собираются крупные интерфейсные блоки. Затем идут facades, объединяющие модули в большие страницы или экранные формы. Наконец, верхние уровни behavior и app организуют сложное поведение и итоговую сборку приложения.
Такой путь легко читать и объяснять новым участникам команды. Он намного лучше воспринимается, чем хаотичная система директорий, где reusable-компоненты, страницы, state management и прикладные сценарии лежат вперемешку.
Какие ошибки возможны даже в improved FSD
Ни одна структура не спасает автоматически. Даже очень строгая схема начинает деградировать, если команда перестает уважать смысл слоев. На практике самые частые ошибки здесь предсказуемы.
Первая ошибка — попытка протащить предметную логику вниз, в tools или utils, чтобы «удобнее переиспользовать». Вторая — превращение facades в монолитные страницы, которые опять знают обо всем. Третья — размывание behavior, когда туда начинает попадать любая сложная функция, даже если это не orchestration эффектов, а просто кусок логики. Четвертая — превращение packages в огромный инфраструктурный склад без четких границ.
То есть строгая архитектура все равно требует архитектурной дисциплины. Но ее преимущество в том, что ошибка становится заметнее. Если папка названа точно, сложнее притвориться, что таблица — это «просто tool», а глобальный стор — это «маленький util».
Кому подойдет такой подход
Improved FSD лучше всего подходит для средних и крупных React-проектов, где есть несколько разработчиков, долгий жизненный цикл продукта и высокая цена архитектурного хаоса. Особенно хорошо он работает там, где в интерфейсе много больших прикладных модулей, сложных сценариев загрузки данных, страниц-сборок и длительной эволюции функциональности.
Для очень маленького проекта такая схема может показаться избыточной. Если приложение состоит из пары экранов и десятка компонентов, затраты на строгую архитектуру могут не окупиться сразу. Но как только команда начинает замечать повторяющиеся проблемы с зависимостями, хаотичными импортами и трудным рефакторингом страниц, подобная структура начинает давать реальную пользу.
Стоит подчеркнуть и более общий смысл: ценность строгой архитектуры не в названии папок, а в том, что она раскрывает смысл каждого уровня и делает поток зависимостей читаемым прямо из дерева проекта. Именно это и отличает подход от косметической перекладки файлов: правила границ перестают жить только в голове и становятся видимой частью кодовой базы.
Заключение
Improved FSD — это не отказ от Feature-Sliced Design, а попытка сделать его практичнее и строже для реального React-проекта. Вместо слишком общей схемы приложение получает ясные уровни: app для сборки и базовой верстки, behavior для сложных поведений и эффектов, facades для больших страниц, modules для крупных интерфейсных блоков, packages для данных и стора, tools для базовых компонентов, utils для мелких хелперов и types для контрактов.
Главное достоинство этой схемы в том, что она навязывает полезную строгость. Нижележащие уровни не могут зависеть от вышележащих. Значит, кодовая база остается понятнее, граф зависимостей — чище, а циклические связи — намного менее вероятными. Для больших React-приложений это не косметическое улучшение, а реальный архитектурный выигрыш.
Если команда уже выросла из папки components, устала от бесформенных страниц и хочет, чтобы дерево проекта само подсказывало направление зависимостей, improved FSD выглядит очень сильным шагом вперед. Это один из тех случаев, когда правильная структура не просто украшает репозиторий, а напрямую влияет на скорость разработки, качество рефакторинга и срок жизни всей системы.
Если сформулировать главный вывод совсем прямо, он будет таким: сила improved FSD не в красоте названий слоёв, а в том, что дерево директорий становится материализованным направленным графом зависимостей — нижнее не знает о верхнем, и поэтому архитектурное нарушение приходится совершать явно, а не получать его случайно через расплывчатые границы.