Какую проблему решает tRPC

При создании REST API на TypeScript сервер определяет структуру ответа. Клиенту приходится вручную создавать соответствующие типы TypeScript. Со временем эти типы расходятся по мере развития API, а компилятор не может обнаружить несоответствие, поскольку типы определены в разных пакетах.

Переименованное поле на сервере превращается в незаметную ошибку во время выполнения на клиенте.

GraphQL устраняет расхождение типов, генерируя типы TypeScript из схемы с помощью таких инструментов, как graphql-codegen. Этот подход хорошо работает, но усложняет проект: появляется отдельный язык запросов, GraphQL SDL, этап генерации кода в конвейере сборки и инструменты управления схемой.

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

Подход tRPC радикально прост: определите процедуры API на сервере как функции TypeScript, экспортируйте тип маршрутизатора и импортируйте этот тип на клиенте. Генерация кода не требуется. Отдельный язык схем также не нужен.

Сам компилятор TypeScript проверяет контракт между клиентом и сервером во время сборки.

tRPC требует, чтобы сервер и клиент совместно использовали типы через импорты TypeScript. Это естественно работает в монорепозитории, например Turborepo, Nx или рабочих пространствах pnpm, где сервер и клиент являются отдельными пакетами и могут импортировать друг друга.

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

На сервере определите маршрутизатор и экспортируйте его тип: export type AppRouter = typeof appRouter. На клиенте импортируйте этот тип и создайте типизированный клиент: createTRPCReact(). Клиент точно знает, какие процедуры существуют и каковы их типы входных и выходных данных.

Переименование процедуры на сервере немедленно вызывает ошибку TypeScript на клиенте.

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

На практике это улучшение опыта разработчика — наиболее высоко оцениваемая возможность tRPC.

По умолчанию tRPC использует HTTP в качестве транспорта. Каждый вызов процедуры является HTTP-запросом. tRPC также поддерживает WebSockets для подписок. Транспорт — это деталь реализации; программный интерфейс клиента одинаков независимо от транспорта.

Вы также можете предоставлять процедуры tRPC в виде стандартных конечных точек REST с помощью адаптера REST, чтобы обеспечить совместимость с клиентами, не использующими tRPC.

tRPC работает как промежуточное ПО в Express, Fastify и Hono. В Next.js он интегрируется через обработчики маршрутов API. Стартовый шаблон create-t3-app, то есть T3 Stack, объединяет tRPC, Prisma, NextAuth и Tailwind в полноcтековый шаблон Next.js.

T3 Stack — наиболее популярная отправная точка для tRPC, демонстрирующая готовые к промышленной эксплуатации подходы.

Другой типобезопасный подход к REST — определить схемы Zod, автоматически создать спецификацию OpenAPI и сгенерировать типы TypeScript на основе этой спецификации. Это создаёт контракт API, который могут использовать клиенты, написанные не на TypeScript.

tRPC проще, но работает только с TypeScript. OpenAPI и Zod усложняют решение, зато создают публичный контракт API. Выбирайте tRPC для внутреннего взаимодействия TypeScript с TypeScript, а OpenAPI — для публичных API.

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

Понимание этой области применения помогает не внедрять tRPC там, где лучше подходят REST или GraphQL.

Команда npm create t3-app@latest создаёт каркас проекта Next.js с предварительно настроенными tRPC, Prisma, NextAuth.js, Tailwind CSS и TypeScript. Сгенерированный код демонстрирует структуру маршрутизатора, создание контекста и настройку клиента.

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

Как tRPC совместно использует типы между сервером и клиентом без генерации кода?

tRPC устраняет расхождение типов между клиентом и сервером на TypeScript, напрямую импортируя тип TypeScript маршрутизатора и избавляя от необходимости генерировать код. Он работает в монорепозиториях и интегрируется с Next.js, Express, Fastify и Hono. T3 Stack (create-t3-app) — стандартный стартовый шаблон для промышленной разработки.

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