Полевое руководство по экосистеме TanStack

TanStack — это набор headless, типобезопасных, компонуемых библиотек для работы с получением данных, маршрутизацией, таблицами, формами, виртуализацией и клиентским состоянием. Экосистема выросла из React Query, впоследствии переименованного в TanStack Query. Библиотеки для работы с данными и UI поставляются с адаптерами для React, Vue, Solid, Svelte и Angular, тогда как роутер и полностековый фреймворк ориентированы на React и Solid. TanStack сам по себе не является фреймворком; проект описывает свои компоненты как headless, компонуемые утилиты, и лишь один из них — TanStack Start — является полностековым фреймворком.

Если вы уже используете TanStack Query и регулярно встречаете упоминания Router, Start, Table, Form, Store, DB и AI, практическая задача состоит в том, чтобы разобраться, что делает каждый из них, насколько он зрел и когда стоит обратиться к нему вместо стандартного стека React (Next.js, React Router, Redux/Zustand, React Hook Form, Apollo, AG Grid). Это руководство описывает экосистему библиотека за библиотекой, приводит минимальную сигнатуру кода для каждой, обозначает степень зрелости номером версии и показывает, как компоненты связаны между собой. Это карта, а не учебник — шаги по настройке находятся в официальной документации, ссылки на которую приведены по всему тексту.

Что такое TanStack и почему важна концепция «headless»

TanStack — это набор независимых библиотек, объединённых одним принципом проектирования: библиотека владеет логикой, вы владеете отрисовкой. Каждая библиотека TanStack разделяет состояние и разметку — библиотека запускает конечный автомат состояний, а ваш компонент решает, как выглядит интерфейс. Именно это на практике означает «headless»: никакого CSS TanStack для переопределения, никаких компонентов TanStack для расширения, никакого навязанного мнения о том, как должен выглядеть ваш UI. TanStack Query является отправной точкой бренда — он был переименован из React Query по мере роста экосистемы, — хотя TanStack Table появился ещё до ребрендинга, так что Query является популяризирующей точкой отсчёта, но не буквально первой библиотекой.

Общая философия часто формулируется как «владей своим кодом, а не своим фреймворком». Из неё вытекают три свойства:

• Headless: логика без UI. Вы подключаете состояние библиотеки к любой разметке, дизайн-системе или слою доступности, которые уже используете.
• Независимость от фреймворка на уровне ядра: библиотеки для работы с данными и UI — Query, Table, Form, Virtual и Store — поставляются с официальными адаптерами для React, Vue, Solid, Svelte и Angular. Маршрутизация является исключением: TanStack Router и TanStack Start ориентированы только на React и Solid.
• Компонуемость вместо монолитов: каждая библиотека работает как самостоятельно, так и совместно с другими. Вы можете использовать Query без Router или Table без Start.

Карта библиотек

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

TanStack Query — серверное состояние

TanStack Query управляет асинхронным серверным состоянием: получением данных, кешированием, фоновым обновлением, дедупликацией и оптимистичными обновлениями. Он заменяет ручной паттерн fetch + useEffect, с которого начинало большинство React-приложений. Библиотека стабильна.

// @tanstack/react-query v5.101.0
const { data: users, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then((res) => res.json()),
});

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

TanStack Router — типобезопасная маршрутизация

TanStack Router — это полностью типобезопасный клиентский роутер для React и Solid. Пути маршрутов, параметры URL, параметры поиска, контекст маршрута и данные загрузчика типизированы сквозным образом, поэтому компилятор, а не пользователь во время выполнения, обнаруживает ссылку с неверной формой параметра. Он заменяет React Router для SPA и является стабильным.

// @tanstack/react-router v1.170.16
const Route = createFileRoute('/products')({
  validateSearch: (search) => ({
    category: (search.category as string) ?? 'all',
    page: Number(search.page ?? 1),
  }),
});

const { category, page } = Route.useSearch();

Router обрабатывает параметры поиска URL как типизированное, валидированное состояние, что делает фильтры, порядок сортировки и пагинацию доступными для передачи через URL и восстановления при обновлении страницы. Это решает конкретный, воспроизводимый класс ошибок: записи сессий SPA-дашбордов регулярно показывают, как пользователи теряют состояние фильтрации, сортировки и пагинации при обновлении страницы или навигации назад, когда это состояние хранилось в памяти компонента, а не в URL — именно этот сценарий сбоя и устраняют типизированные параметры поиска.

TanStack Table — headless сетки данных

TanStack Table берёт на себя логику сеток данных — определения столбцов, сортировку, фильтрацию, пагинацию, выбор строк, группировку и видимость столбцов — оставляя каждый пиксель UI вам. Он утвердил headless-паттерн в экосистеме React и заменяет самоуверенные библиотеки сеток, такие как AG Grid и MUI DataGrid, для команд, которым нужен полный контроль над разметкой. Библиотека стабильна; ветка V9 находится в разработке и пока не является опубликованной версией latest.

// @tanstack/react-table v8.21.3
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

Экземпляр Table управляет состоянием; ваша разметка отрисовывает то, что описывает это состояние. В сочетании с Query для серверной пагинации и фильтрации он обрабатывает большие наборы данных без загрузки всего на клиент.

TanStack Form — типизированные формы

TanStack Form управляет состоянием форм и валидацией — ошибками на уровне поля и формы, синхронной и асинхронной валидацией, состоянием отправки — ничего не отрисовывая самостоятельно. Это headless-преемник React Hook Form, и он стабилен (v1).

// @tanstack/react-form v1.33.0
const form = useForm({
  defaultValues: { email: '', password: '' },
  onSubmit: async ({ value }) => { await loginUser(value); },
});

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

TanStack Virtual — виртуализация списков и сеток

TanStack Virtual отрисовывает только строки или столбцы, находящиеся в текущей области просмотра, для больших прокручиваемых списков и сеток, сохраняя DOM небольшим при огромном наборе данных. Библиотека предоставляет вам размеры и смещения; разметку отрисовываете вы. Она заменяет написанные вручную решения для оконного отображения и библиотеки вроде react-window и react-virtualized. Библиотека стабильна.

// @tanstack/react-virtual v3.14.3
const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 48,
});

const rows = virtualizer.getVirtualItems();

useVirtualizer возвращает виртуальные элементы в области просмотра и общий размер; вы позиционируете каждый элемент абсолютно по его смещению. Библиотека естественным образом сочетается с Table для больших сеток данных — Table управляет моделью строк, Virtual сохраняет в DOM только видимые строки, — так что список из пяти тысяч строк прокручивается с полной скоростью.

TanStack Store — клиентское состояние

TanStack Store — это реактивное хранилище с тонкой гранулярностью, которое лежит в основе нескольких других библиотек TanStack и доступно как самостоятельный пакет. Оно предлагает альтернативу Zustand и Redux для клиентского (не серверного) состояния. Как самостоятельный пакет оно находится в альфа-версии (v0.11.0), поэтому к формулировкам вроде «заменяет Zustand/Redux» следует относиться с учётом этой степени зрелости.

// @tanstack/store v0.11.0 + @tanstack/react-store
import { Store } from '@tanstack/store';
import { useStore } from '@tanstack/react-store';

const countStore = new Store(0);
// в компоненте:
const count = useStore(countStore);

Разделение ответственности — это полезная ментальная модель: Query управляет серверным состоянием, Store — клиентским. Для большинства приложений Query в сочетании с небольшим количеством Store (или вашим существующим инструментом для клиентского состояния) покрывает всю поверхность состояний.

TanStack Start — полностековый фреймворк

TanStack Start — это полностековый React-фреймворк, построенный поверх TanStack Router. Он привносит файловую маршрутизацию, серверные функции, потоковый SSR и сквозной TypeScript, сохраняя при этом прозрачность базовых механизмов. Он позиционируется как альтернатива Next.js и Remix. Start находится на стадии Release Candidate (текущая ветка релизов 1.168.x), ещё не объявлен стабильным, а его поддержка React Server Components доступна в экспериментальном режиме, а не как производственный вариант по умолчанию.

// @tanstack/react-start v1.168.26
import { createServerFn } from '@tanstack/react-start';

const getUser = createServerFn({ method: 'GET' })
  .validator((userId: string) => userId)
  .handler(async ({ data: userId }) => db.users.findById(userId));

Серверные функции — это типизированные, совмещённые с клиентским кодом функции, которые выполняются на сервере, но вызываются из клиентских компонентов как любая асинхронная функция. Типы передаются от источника данных до компонента без ручных аннотаций, и для простого получения данных не нужно поддерживать отдельный слой API. Обратите внимание, что путь импорта — @tanstack/react-start; старые руководства, показывающие @tanstack/start, устарели.

TanStack DB — реактивное клиентское хранилище

TanStack DB — это реактивное, клиент-ориентированное хранилище с коллекциями, живыми запросами и оптимистичными мутациями. Вы определяете коллекции, пишете запросы к ним, и любой компонент, наблюдающий за запросом, перерисовывается при изменении базовых данных — будь то серверная синхронизация, локальная мутация или оптимистичное обновление. Он располагается перед вашим собственным бэкендом или API; это клиентский слой хранения и синхронизации, а не замена Firebase или Supabase как backend-as-a-service. Библиотека находится в бета-версии (v0.6.9).

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

TanStack AI — провайдеро-независимые AI-примитивы

TanStack AI предоставляет headless-примитивы для функций на основе ИИ — обработку потоковых ответов, состояние диалога и унифицированный интерфейс для разных провайдеров моделей — без привязки к конкретному SDK или провайдеру. Библиотека находится в бета-версии, как объявлено в блоге TanStack, а не в альфа-версии или экспериментальном режиме.

Потоковые ответы (токены, поступающие постепенно) обрабатываются нативно, что и делает интерфейсы AI-чата и генерации отзывчивыми. Ценность носит архитектурный характер: провайдеро-независимый слой позволяет вам свободно менять провайдеров моделей без переписывания UI-состояния.

Таблица зрелости

Степень зрелости существенно варьируется по всей экосистеме, и наиболее распространённая ошибка в обзорах экосистем — представлять экспериментальные библиотеки как устоявшиеся. Пять из девяти рассмотренных здесь библиотек — Query, Router, Table, Form и Virtual — стабильны по состоянию на июнь 2026 года; Start находится на стадии Release Candidate с экспериментально доступной поддержкой React Server Components; DB и AI — в бета-версии; Store — в альфа-версии. В таблице ниже указаны опубликованная версия и статус каждой библиотеки.

Актуальный статус релизов проверяйте в документации по ссылкам.

Как компоненты сочетаются друг с другом

Библиотеки спроектированы для совместного использования, и центральная интеграция — это загрузчики Router, предварительно загружающие данные Query, чтобы компонент отрисовывался на основе прогретого кеша. Загрузчик маршрута может вызвать queryClient.ensureQueryData до монтирования компонента; к моменту отрисовки данные уже будут закешированы. Когда Start добавляет SSR в этот конвейер, данные предварительно загружаются на сервере и дегидратируются, поступая в виде полностью отрисованного HTML при первом запросе.

// @tanstack/react-router v1.170.16 + @tanstack/react-query v5.101.0
const Route = createFileRoute('/users/$userId')({
  loader: ({ params }) =>
    queryClient.ensureQueryData({
      queryKey: ['user', params.userId],
      queryFn: () => fetchUser(params.userId),
    }),
  component: UserPage,
});

Стоит выделить три конкретных связи:

1. Router → Query: загрузчики маршрутов предварительно загружают данные Query, устраняя мигание загрузки при первой отрисовке.
2. Start → Router: Start построен поверх Router, поэтому типизированная маршрутизация и модель загрузчиков напрямую переносятся в полностековый фреймворк с добавлением SSR и дегидратации.
3. Table → Query: Table потребляет пагинированные, отфильтрованные данные из Query для серверной пагинации, поэтому сетка обрабатывает большие наборы данных без загрузки всего на клиент.

Выбор между TanStack и устоявшимися решениями

Выбирайте TanStack Start для публичных страниц, которые должны индексироваться и распространяться, и TanStack Router отдельно — для авторизованных дашбордов, где SEO не важно, а приоритетом является производительность на стороне клиента. Это решение о стратегии отрисовки является первым архитектурным выбором и предшествует любому выбору библиотеки — это продуктовое решение, а не техническое предпочтение.

• Публичные сайты (маркетинговые страницы, блоги, контентные продукты) нуждаются в SSR. Поисковые роботы ненадёжно выполняют JavaScript; основные показатели Web Vitals, такие как LCP, CLS и INP, являются сигналами ранжирования Google; метаданные Open Graph считываются из ответа сервера. Start доставляет полностью отрисованный HTML при первом запросе.
• Авторизованные приложения (дашборды, внутренние инструменты, клиентские порталы) в любом случае не могут быть проиндексированы, работают на основе сессий и состояния и ставят во главу угла время до интерактивности. SPA на одном Router — без SSR-механизма Start — нередко оказывается более лёгким решением.

Что касается выбора между библиотеками и устоявшимися решениями, экосистема чётко соответствует стандартным инструментам React:

Когда не стоит использовать TanStack

Headless, типобезопасная модель TanStack является сильным выбором по умолчанию, но реальным недостатком в трёх ситуациях, и честная карта их называет. Модель плохо подходит, когда команде нужны готовые стилизованные компоненты из коробки, когда ваш кадровый резерв знает Redux и React Router, но не TanStack, или когда вам нужна стабильная поддержка React Server Components в продакшне уже сегодня — поскольку поддержка RSC в Start всё ещё экспериментальная, Next.js и React Hook Form остаются более прагматичным выбором в этих случаях.

Конкретнее:

• Потребность в готовых стилизованных компонентах: headless означает, что UI строите вы. Если вам нужна сетка или форма, которая выглядит завершённой сразу после установки, AG Grid, MUI или готовый набор компонентов окажутся быстрее.
• Знакомство команды и найм: больше разработчиков знают Redux, React Router и Next.js. Кривая обучения и меньший кадровый резерв — это реальные издержки при масштабировании команды.
• RSC в продакшне уже сегодня: Next.js имеет годы боевого тестирования React Server Components в продакшне; поддержка RSC в Start является экспериментальной по состоянию на июнь 2026 года.
• Ранние библиотеки: Store (альфа), DB (бета) и AI (бета) ещё не являются производственным вариантом по умолчанию. Используйте их с учётом этой степени зрелости и следите за версией и статусом в документации по ссылкам.

Помимо рассмотренных здесь библиотек, TanStack поддерживает утилитарный уровень — включая Virtual, Pacer, Ranger и DevTools, — который следует тому же headless, типобезопасному паттерну в меньшем масштабе.

С чего начать

Если вы ещё не используете Query, начните с него — это изменение с наибольшей отдачей для React-кодовой базы, которое ни к чему больше вас не обязывает. Обратитесь к Router для нового SPA, а не для миграции существующего приложения, и рассматривайте Start как выбор для новых публичных сайтов, которым нужен SSR, следя при этом за его статусом RC. Для библиотек на ранних стадиях — Store, DB и AI — пусть актуальная таблица зрелости и официальная документация по ссылкам, а не ажиотаж вокруг экосистемы, определяют, готова ли библиотека к той роли, которую вы для неё планируете.

Часто задаваемые вопросы

В чём разница между TanStack Query и TanStack DB?

TanStack Query управляет асинхронным серверным состоянием посредством получения данных, кеширования, фонового обновления и дедупликации, рассматривая сервер как источник истины, который клиент отражает. TanStack DB — это реактивное, клиент-ориентированное хранилище с коллекциями, живыми запросами и оптимистичными мутациями, которое располагается перед вашим собственным бэкендом для приложений с интенсивной работой с данными, требующих обновлений в реальном времени и сложной клиентской фильтрации. Query стабилен; DB находится в бета-версии по состоянию на июнь 2026 года.

Можно ли использовать библиотеки TanStack с Vue, Svelte или Angular вместо React?

Да, для библиотек данных и UI. Query, Table, Form, Virtual и Store поставляются с официальными адаптерами для React, Vue, Solid, Svelte и Angular. Маршрутизация является исключением: TanStack Router и полностековый фреймворк TanStack Start ориентированы только на React и Solid. Таким образом, команда Vue или Angular может использовать Query и Table, но не может использовать TanStack Router для типобезопасной маршрутизации.

Готов ли TanStack Start к продакшну как замена Next.js?

Не полностью, по состоянию на июнь 2026 года. TanStack Start находится на стадии Release Candidate в ветке релизов 1.168.x, ещё не объявлен стабильным, а его поддержка React Server Components доступна только в экспериментальном режиме, а не как производственный вариант по умолчанию. Если вам нужен стабильный RSC в продакшне уже сегодня, Next.js имеет годы боевого тестирования этой функции. Start является разумным выбором для новых публичных SSR-сайтов, где экспериментальный RSC приемлем.

Нужно ли принимать всю экосистему TanStack, чтобы использовать одну библиотеку?

Нет. Каждая библиотека TanStack независима и компонуема, поэтому вы можете использовать Query без Router или Table без Start. Библиотеки интегрируются при совместном использовании (например, загрузчики маршрутов могут предварительно загружать данные Query), но ни одна из них не требует других. Query является наиболее распространённой точкой входа, поскольку это изменение с наибольшей отдачей для существующей React-кодовой базы, которое ни к чему больше в экосистеме вас не обязывает.