tRPC: сквозные типы без кодогенерации и чего это стоит

Весь трюк: typeof appRouter

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

// server/router.ts
import { initTRPC } from "@trpc/server";
import { z } from "zod";
const t = initTRPC.create();

export const appRouter = t.router({
  getUserById: t.procedure
    .input(z.object({ id: z.number(), includeDeleted: z.boolean() }))
    .query(({ input }) => findUser(input.id)), // возвращает User
});

export type AppRouter = typeof appRouter; // ^? тип всего роутера

// client/trpc.ts
import { createTRPCClient, httpBatchLink } from "@trpc/client";
import type { AppRouter } from "../server/router"; // только тип — см. ниже

const trpc = createTRPCClient<AppRouter>({ links: [httpBatchLink({ url: "/trpc" })] });

const user = await trpc.getUserById.query({ id: 42, includeDeleted: false });
// ^? User  — выведено сквозь из типа возврата сервера
// trpc.getUser  // Error: Property 'getUser' does not exist

createTRPCClient<AppRouter> берёт тип роутера сервера и через большой внутренний mapped/conditional-тип превращает его в интерфейс вызовов клиента: процедура getUserById.query роутера appRouter становится trpc.getUserById.query(input): Promise<output>. Тип входа берётся из z.infer вашей zod-схемы; тип выхода — из типа возврата резолвера. Оба текут к клиенту без единого сгенерированного файла. (В реальном приложении вы редко вызываете .query напрямую — вы прогоняете его через клиентский кэш вроде React Query, где эти выведенные типы доходят до ваших хуков; см. трек Frontend про клиентские кэши.)

«Без кодогена» — что это реально значит и жёсткие пределы

Прежде чем брать tRPC в следующий проект, спросите себя: может ли клиент всегда сделать import type с сервера? Если да — живой вывод достаётся бесплатно. Если нет — нужен контракт провода, и это меняет всё.

REST + OpenAPI генерирует файл client.ts из спеки; GraphQL (язык запросов с типизированной схемой) генерирует типы из схемы. tRPC не генерирует ничего. Размен в том, что клиент обязан мочь сделать import type серверного AppRouter — а это значит:

• Одна сборка TypeScript / монорепо. Клиент и сервер компилируются вместе (или сервер поставляет .d.ts, который потребляет клиент). Формата провода, описывающего API, нет; тип — это контракт, а тип может пересечь только границу компиляции, не границу сети или языка.
• TypeScript на обоих концах. Swift- или Kotlin-клиент не может потребить TS-тип. Для полиглот- или сторонних потребителей нужен настоящий контракт провода — OpenAPI или GraphQL — и именно тогда их кодогенерация окупается.

Цена: время вывода роутера и лаги редактора

За удобство платят работой компилятора. Тип клиента — функция от всего типа роутера сервера, пересчитываемая tsc и языковым сервисом редактора. На роутере с сотнями процедур, глубоко вложенными саброутерами и сложными zod-схемами вы это чувствуете: всплывающие подсказки крутятся, автодополнение лагает, прогоны tsc ползут. Вывод не кэшируется так, как кэшировался бы сгенерированный файл — файла нет. Смягчения:

• Разбивайте на саброутеры и избегайте одного монолитного роутера на 500 процедур; меньшие единицы перевыводятся быстрее.
• Аннотируйте типы возврата процедур явно, чтобы тип выхода резолвера не выводился каждый раз сквозь весь слой данных.
• Держите zod-схемы разумными — гигантский z.discriminatedUnion на 40 членов дорог в выводе везде, где используется.
• Тянитесь к кодогену, когда вывод перестаёт масштабироваться: это настоящая точка, где модель OpenAPI/GraphQL «сгенерировал раз — прочитал файл» выигрывает по производительности компилятора, разменивая живой вывод на шаг сборки.

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

Главный самострел: случайный импорт серверного рантайма

Поскольку сервер и клиент живут в одном репо, легко написать import { appRouter } (значение) вместо import type { AppRouter } (тип). Импорт значения тащит весь серверный рантайм — драйверы БД, секреты, Node-only-модули — в бандл клиента и даже может отправить учётные данные в браузер. Всегда import type для роутера на клиенте. Включите "verbatimModuleSyntax": true (раздел 07), чтобы случайный импорт-значением типа был ошибкой компиляции, а не тихим раздуванием бандла.