Мой первый боевой проект: FSD, TanStack и как мы это дружили

Тут я расскажу о том, как я впервые с нуля поднимал проект на React, используя связку FSD, TanStack Router, TanStack Query и Effector — и как мы всё это далее подружили подружили или нет.

Сразу оговорюсь:

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

• А так же, это моя первая статья. Не претендую на истину в последней инстанции, но надеюсь, кому‑то мой опыт будет полезен и палками бить сильно не будете.

Описание проекта

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

В качестве UI‑библиотеки выбран Ant Design, кастомизированный под нужды проекта.

Формально мы переписывали существующее Angular 12-приложение, но фактически вся архитектура создавалась заново: маршрутизация, состояние, взаимодействие с API.

Почему именно TanStack Query, Router и Effector?

TanStack Query был выбран из‑за его мощности в работе с запросами: встроенное кеширование, повторные попытки запросов, фоновая подгрузка, бесконечная пагинация — всё это из коробки и без костылей. Благодаря кешу снижается количество реальных сетевых запросов (количество пользователей системы — примерно 9000 человек).

Некоторые фичи этого решения будут подробнее показаны ниже, в том числе пример с useInfiniteQuery.

Далее логично за TanStack Query пришёл и TanStack Router, потому что они отлично стакаются вместе: можно грузить данные прямо во время перехода между страницами, используя loader прямо в конфигурации маршрута. Также из коробки — различные фичи по типу beforeLoad и валидации параметров маршрута.

Effector же я подключил не для хранения данных с бэка — этим у нас занимается TanStack Query как основной асинхронный стейт‑менеджер.

Effector нужен для другого: упростить взаимодействие между разнесёнными компонентами, например, когда форма где‑то глубоко, а кнопка «Сохранить» — наверху. Как это работает — покажу ниже в статье.

Такой стек дал гибкость, контроль и внятное разделение зон ответственности между слоями — и при этом, как мне кажется, не перегружен лишним.

Структура проекта и организация окружения

Да да, в качестве архитектурного фундамента выбран Feature‑Sliced Design (FSD)

Провайдеры

Каждый провайдер вынесен в отдельный компонент.

Работа с API

Бэкенд построен на Java, примерно 300+ эндпоинтов, описанных в OpenAPI спецификации. На первый взгляд, всё хорошо — можно сгенерировать типизированный клиент. Но:

• Многие эндпоинты дублировались (getCard, getCard_1, getCard_2);

• Контракты нестабильны: где‑то null, где‑то "0", где‑то массив из одного объекта;

• ref‑поля не использовались должным образом — никакой вложенной типизации, по факту any.

Мы пробовали разные генераторы: openapi-typescript, orval, heyapi. Все упирались в несовместимость или избыточную сложность.

В итоге остановились на swagger-typescript-api — максимально простой и предсказуемый инструмент.

Плюсы:

• шаблонная генерация без сюрпризов;

• легко настраивается;

• даёт основу, которую можно доработать вручную.

Минусы:

• типизация очень поверхностная;

• отсутствуют связи между сущностями;

• нужно самостоятельно следить за согласованностью моделей и кешей.

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

TanStack Query и ключи кеширования

Эта часть, пожалуй, самая важная — именно из‑за неё я и решил написать статью.
Как только мы внедрили TanStack Query, сразу встал вопрос: как вести ключи кеширования (queryKey)?

Первая реализация казалась жизнеспособной

На старте мы пошли по пути централизованного объекта QUERY_KEYS, где ключи определялись через ApiEntities и параметры методов API:

• Ключи были непрозрачными — без знания API или ApiEntities сложно понять, что за данные кешируются;

• Параметры были слабо читаемы (...params), особенно если объект фильтров сложный;

• Инвалидация требовала знания того, как именно был построен ключ — универсального интерфейса не было.

В какой‑то момент мы поняли: такая схема слишком неудобна и неповоротлива.

Финальная реализация: фабрика ключей и разделение по сущностям

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

Поскольку ключи лучше передавать в виде массива строк:

const info = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList }) // или const info = useQuery({ queryKey: ['todos', 'completed'], queryFn: fetchCompletedTodoList }) // и так может быть ещё несколько запросов с началом queryKey: ['todos', ...]

Так становится удобно инвалидировать кеш по этим значениям. Например, если я захочу инвалидировать весь кеш, связанный с todos, достаточно написать:

queryClient.invalidateQueries({ queryKey: ['todos'] })

И все ключи, начинающиеся с todos, будут инвалидированы. Это очень удобно.

Но я пошёл немного дальше и сделал фабрику генерации ключей:

export function createQueryKey<T extends unknown[]>(namespace: string, ...args: T) {   return [namespace, ...args] as const; }

В итоге для каждого типа запросов я завёл константу с ключами:

import { createQueryKey } from 'shared/api/queryKeys/createQueryKey';  export const userQueryKeys = {   all: () => createQueryKey('users'),   byId: (id: string) => createQueryKey('users', id),   card: (id: string) => createQueryKey('users', id, 'card'),   byFilters: (filters: UserFilters) =>     createQueryKey('users', 'filters', JSON.stringify(filters)), };

Это позволяет удобно использовать ключи в хуках с запросами:

export const useUserCard = (id: string, enabled = true) =>   useQuery({     queryKey: userQueryKeys.card(id),     queryFn: () => getUserCard({ id }),     enabled: enabled && !!id,   });

А инвалидация теперь выглядит так:

queryClient.invalidateQueries({ queryKey: userQueryKeys.all() }); queryClient.invalidateQueries({ queryKey: reestrQueryKeys.byComplexFilter({}) });

Если мы кешируем значение по фильтрам:

export type ReestrUsersComplexFilter = {   status?: string;   roles?: string[];   dateFrom?: string;   dateTo?: string;   search?: string; };  byComplexFilter: (filters: ReestrUsersComplexFilter) =>   createQueryKey('reestrUsers', 'complex', JSON.stringify(filters));

Для сложных объектов используйте JSON.stringify — так ключ будет однозначным (если порядок ключей всегда одинаков).

После всех этих нововведений, работа с ключами в проекте стала куда более предсказуемой — код, структура, подходы к запросам и кешированию теперь заданы довольно чётко. И легко инвалидировать кеш как локально по определённым запросам, так и глобально по модулю.

Effector и зачем я его вообще взял

Да, TanStack Query сам по себе является асинхронным стейт‑менеджером, но Effector здесь не просто так — он решает конкретную задачу:

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

Самый простой пример:
Я использую AntD форму, которая расположена глубоко в компоненте. А кнопку «Сохранить» хочу разместить в Header родительского роута — или вообще вынести в другой виджет.

То есть:

• Кнопка «Сохранить» — в одном месте;

• Вызов мутации формы — в другом, внутри формы.

Передавать коллбеки пропсами — невозможно. Использовать контекст — громоздко и неявно.
А вот Effector дал простой и удобный способ: создать event, на который подписана форма, и триггерить его из кнопки.

Таким образом, Effector стал связующим звеном между UI‑блоками, особенно в сложных сценариях с вложенными роутами и формами.

Итоги

TanStack Router и TanStack Query отлично работают в связке поскольку они в одной набирающей популярность экосистеме TanStack. Их API и подходы к состоянию, загрузке данных и потоку данных очень хорошо сочетаются.

Один из главных плюсов: возможность запрашивать данные прямо в конфигурации маршрутов.

const postsLayoutRoute = createRoute({   getParentRoute: () => rootRoute,   path: 'posts',   loader: ({ context: { queryClient } }) =>     queryClient.ensureQueryData(postsQueryOptions), }).lazy(() =>   import('./posts.lazy').then((d) => d.Route) )  const postsIndexRoute = createRoute({   getParentRoute: () => postsLayoutRoute,   path: '/',   component: PostsIndexRouteComponent, })

Загрузка данных заранее, до рендера компонента, происходит типобезопасно, синхронно с маршрутизацией и без лишних ручных проверок.

Сам по себе TanStack Query — это мощный инструмент для работы с данными. Он покрывает практически все потребности, включая:

• кеширование,

• повторные попытки,

• загрузку по требованию,

• фоновое обновление,

• пагинацию и бесконечную прокрутку

// Простой пример с бесконечной пагинацией const {   data,   error,   fetchNextPage,   hasNextPage,   isFetching,   isFetchingNextPage,   status, } = useInfiniteQuery({   queryKey: ['projects'],   queryFn: fetchProjects,   initialPageParam: 0,   getNextPageParam: (lastPage) => lastPage.nextCursor, })

А если бэкенд не предоставляет nextCursor, и приходится рассчитывать это вручную — TanStack Query тоже справляется

Важно сказать что не стоит пытаться класть результаты запроса из TanStack Query в сторы Effector, это плохая идея, если сильно хочется то лучше взять Farfetched, но тут есть уже свои моменты.