Настройка tRPC с React и Next.js

Установите @trpc/server и @trpc/client — основные пакеты tRPC. Добавьте @trpc/react-query как адаптер хуков React и @tanstack/react-query как пиринговую зависимость, обеспечивающую работу этих хуков.

Для интеграции маршрута API Next.js в последних версиях tRPC дополнительный пакет адаптера не требуется.

Создайте файл server/trpc.ts и вызовите initTRPC.create(), чтобы получить объект t. Экспортируйте t.router под именем router, t.procedure под именем publicProcedure, а t.mergeRouters — как вспомогательную функцию.

Фабрика initTRPC принимает обобщённый тип контекста, который определяет, какие данные доступны в аргументе ctx каждой процедуры.

Процедура определяется добавлением .input(zodSchema).query(handler) или .mutation(handler) к publicProcedure. Для простой конечной точки приветствия: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Схема Zod предоставляет и типы TypeScript, и проверку входных данных во время выполнения.

Создайте appRouter с помощью функции router(): router({ hello: helloHandler, users: usersRouter }). Вложенные маршрутизаторы позволяют организовать процедуры по предметным областям (пользователи, публикации, комментарии) в отдельных файлах.

Экспортируйте тип AppRouter: export type AppRouter = typeof appRouter. Именно этот тип будет импортировать клиент.

Создайте app/api/trpc/[trpc]/route.ts (маршрутизатор приложения) или pages/api/trpc/[trpc].ts (маршрутизатор страниц). Используйте fetchRequestHandler из @trpc/server/adapters/fetch, чтобы обрабатывать все запросы tRPC через этот единый универсальный маршрут.

Передайте в fetchRequestHandler маршрутизатор, функцию createContext и объекты запроса и ответа.

Создайте файл utils/trpc.ts. Вызовите createTRPCReact(), чтобы создать типизированный объект клиента trpc. У этого объекта есть свойство для каждой процедуры маршрутизатора, и каждое свойство предоставляет хуки React Query.

Тип AppRouter импортируется из файла сервера; TypeScript отслеживает цепочку импортов и проверяет все варианты использования.

В макете приложения или в _app.tsx создайте экземпляр QueryClient и экземпляр клиента tRPC с помощью trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Оберните дерево компонентов одновременно в trpc.Provider (с клиентом trpc) и QueryClientProvider (с QueryClient). Оба провайдера обязательны.

В любом компоненте: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). Хук полностью типизирован: data имеет выведенный тип результата процедуры hello, а объект входных данных проверяется на соответствие схеме Zod.

Передача входных данных неправильного типа приводит к ошибке компиляции TypeScript, а не к ошибке во время выполнения.

Чтобы tRPC работал, клиент должен иметь возможность импортировать типы из файла сервера. В проекте Next.js код сервера и клиента компилируется одним экземпляром TypeScript, поэтому импорты работают без дополнительной настройки.

В монорепозитории с отдельными пакетами настройте ссылки на проекты TypeScript или псевдонимы путей в tsconfig.json, указывающие на пакет сервера.

Обработчик tRPC выполняется на сервере (как маршрут API Next.js или пограничная функция). Клиент tRPC выполняется в браузере. TypeScript обрабатывает импорты типов на этапе сборки, не выполняя код сервера в браузере.

На клиенте импортируется только тип AppRouter, а не фактическая реализация, поэтому секреты сервера не попадут в пакет клиента.

Запустите сервер разработки Next.js и откройте консоль браузера. Вызов trpc.hello.useQuery должен вывести ответ сервера. Откройте вкладку «Сеть», чтобы увидеть HTTP-запрос к /api/trpc/hello, в котором входные данные переданы как параметр запроса.

По умолчанию httpBatchLink объединяет несколько одновременных запросов в один HTTP-вызов — это видно на диаграмме сетевых запросов.

Какая функция инициализирует экземпляр tRPC и предоставляет фабрики маршрутизаторов и процедур?

Установите @trpc/server, @trpc/client, @trpc/react-query и @tanstack/react-query. Инициализируйте tRPC с помощью initTRPC.create(), определите процедуры и экспортируйте тип AppRouter. Создайте универсальный маршрут API Next.js, настройте TRPCProvider и QueryClientProvider, а затем вызывайте процедуры с помощью trpc.procedureName.useQuery().

TypeScript проверяет весь контракт между клиентом и сервером на этапе компиляции без генерации кода.