Konfiguracja tRPC z Reactem i Next.js

Należy zainstalować @trpc/server i @trpc/client — podstawowe pakiety tRPC. Należy również dodać @trpc/react-query jako adapter hooków React oraz @tanstack/react-query jako zależność peer, która zapewnia działanie tych hooków.

W nowszych wersjach tRPC integracja z trasami API Next.js nie wymaga dodatkowego pakietu adaptera.

Należy utworzyć plik server/trpc.ts i wywołać initTRPC.create(), aby uzyskać obiekt t. Należy wyeksportować t.router jako router, t.procedure jako publicProcedure oraz t.mergeRouters jako narzędzie pomocnicze.

Fabryka initTRPC przyjmuje parametr generyczny typu kontekstu, który określa, jakie dane są dostępne w argumencie ctx każdej procedury.

Procedurę definiuje się przez dołączenie .input(zodSchema).query(handler) lub .mutation(handler) do publicProcedure. Prosty endpoint hello może wyglądać tak: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Schemat Zod zapewnia zarówno typy TypeScript, jak i walidację danych wejściowych w czasie działania.

Należy utworzyć appRouter za pomocą funkcji router(): router({ hello: helloHandler, users: usersRouter }). Zagnieżdżone routery pozwalają organizować procedury według domen (users, posts, comments) w osobnych plikach.

Należy wyeksportować typ AppRouter: export type AppRouter = typeof appRouter. To właśnie ten typ zaimportuje klient.

Należy utworzyć app/api/trpc/[trpc]/route.ts (App Router) lub pages/api/trpc/[trpc].ts (Pages Router). Należy użyć fetchRequestHandler z @trpc/server/adapters/fetch, aby obsłużyć wszystkie żądania tRPC za pośrednictwem jednej trasy catch-all.

Do fetchRequestHandler należy przekazać router, funkcję createContext oraz obiekty żądania i odpowiedzi.

Należy utworzyć plik utils/trpc.ts. Należy wywołać createTRPCReact(), aby utworzyć typowany obiekt klienta trpc. Obiekt ten ma właściwość dla każdej procedury w routerze, a każda z nich udostępnia hooki React Query.

Import typu AppRouter pochodzi z pliku serwera; TypeScript podąża za łańcuchem importów, aby sprawdzać poprawność wszystkich zastosowań.

W layoucie aplikacji lub w _app.tsx należy utworzyć instancję QueryClient oraz instancję klienta tRPC za pomocą trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Drzewo komponentów należy opakować zarówno w trpc.Provider (z klientem trpc), jak i QueryClientProvider (z obiektem QueryClient). Obaj dostawcy są wymagani.

W dowolnym komponencie: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). Hook jest w pełni typowany: data ma wywnioskowany typ zwracany przez procedurę hello, a obiekt wejściowy jest sprawdzany względem schematu Zod.

Przekazanie danych wejściowych niezgodnych z typem powoduje błąd kompilacji TypeScript, a nie błąd w czasie działania.

Aby tRPC działało, klient musi mieć możliwość importowania typów z pliku serwera. W projekcie Next.js kod serwera i klienta jest kompilowany przez tę samą konfigurację TypeScript, więc importy działają bez dodatkowej konfiguracji.

W monorepozytorium z osobnymi pakietami należy skonfigurować referencje projektów TypeScript lub aliasy ścieżek w tsconfig.json, wskazujące na pakiet serwera.

Handler tRPC działa na serwerze (jako trasa API Next.js lub Edge Function). Klient tRPC działa w przeglądarce. TypeScript analizuje importy na poziomie typów podczas kompilacji, nie wykonując kodu serwera w przeglądarce.

Po stronie klienta importowany jest tylko typ AppRouter, a nie rzeczywista implementacja, więc sekrety serwera nie trafiają do bundla klienta.

Należy uruchomić serwer deweloperski Next.js i otworzyć konsolę przeglądarki. Wywołanie trpc.hello.useQuery powinno zarejestrować odpowiedź serwera. W zakładce Network należy sprawdzić żądanie HTTP do /api/trpc/hello, z danymi wejściowymi zgrupowanymi w parametrze zapytania.

Domyślny httpBatchLink łączy wiele równoczesnych żądań w jedno wywołanie HTTP, co można zobaczyć na wykresie żądań sieciowych.

Która funkcja inicjalizuje instancję tRPC i udostępnia fabryki routerów oraz procedur?

Należy zainstalować @trpc/server, @trpc/client, @trpc/react-query i @tanstack/react-query. Następnie należy zainicjalizować tRPC za pomocą initTRPC.create(), zdefiniować procedury i wyeksportować typ AppRouter. Kolejne kroki to utworzenie trasy catch-all API Next.js, skonfigurowanie TRPCProvider i QueryClientProvider, a następnie wywoływanie procedur za pomocą trpc.procedureName.useQuery().

TypeScript wymusza zgodność całego kontraktu między klientem a serwerem podczas kompilacji, bez generowania kodu.