Problem rozwiązywany przez tRPC

Podczas tworzenia API REST w TypeScript serwer definiuje kształt odpowiedzi. Klient musi ręcznie utworzyć pasujące typy TypeScript. Z czasem, w miarę rozwoju API, typy te przestają być zgodne, a kompilator nie może wykryć rozbieżności, ponieważ typy są zdefiniowane w osobnych pakietach.

Zmiana nazwy pola na serwerze staje się cichym błędem czasu działania po stronie klienta.

GraphQL rozwiązuje problem rozjeżdżających się typów, generując typy TypeScript ze schematu za pomocą narzędzi takich jak graphql-codegen. Działa to dobrze, ale zwiększa złożoność: dochodzi osobny język zapytań (GraphQL SDL), etap generowania kodu w potoku kompilacji oraz narzędzia do zarządzania schematem.

W przypadku zespołów, które już korzystają z GraphQL, codegen jest właściwym rozwiązaniem. Zespołom, które chcą bezpieczeństwa typów bez narzutu GraphQL, tRPC oferuje alternatywę.

Podejście tRPC wyróżnia się radykalną prostotą: należy zdefiniować procedury API na serwerze jako funkcje TypeScript, wyeksportować typ routera i zaimportować ten typ po stronie klienta. Bez generowania kodu. Bez osobnego języka schematu.

To sam kompilator TypeScript wymusza przestrzeganie kontraktu między klientem a serwerem w czasie kompilacji.

tRPC wymaga, aby serwer i klient współdzieliły typy za pomocą importów TypeScript. Działa to naturalnie w monorepo (Turborepo, Nx, pnpm workspaces), gdzie serwer i klient są osobnymi pakietami, które mogą importować od siebie nawzajem.

W przypadku całkowicie oddzielnego backendu i frontendu trzeba byłoby opublikować typy routera jako współdzielony pakiet. Dodaje to etap publikowania, ale nadal nie wymaga generowania kodu.

Po stronie serwera definiuje się router i eksportuje jego typ: export type AppRouter = typeof appRouter. Po stronie klienta importuje się ten typ i tworzy klienta z typami: createTRPCReact(). Klient dokładnie wie, jakie procedury istnieją oraz jakie są ich typy danych wejściowych i wyjściowych.

Zmiana nazwy procedury na serwerze natychmiast powoduje błąd TypeScript po stronie klienta.

Ponieważ tRPC korzysta bezpośrednio z systemu typów TypeScript, edytor zapewnia po stronie klienta pełne autouzupełnianie nazw procedur, kształtów danych wejściowych i typów zwracanych. Zmiana nazwy procedury jest refaktoryzacją zmiany nazwy w TypeScript, a nie ręcznym wyszukiwaniem i zastępowaniem w całej bazie kodu.

To ulepszenie doświadczenia deweloperskiego jest w praktyce najczęściej chwaloną funkcją tRPC.

Domyślnie tRPC używa HTTP jako transportu. Każde wywołanie procedury jest żądaniem HTTP. tRPC obsługuje również WebSockets na potrzeby subskrypcji. Transport jest szczegółem implementacyjnym; API klienta jest identyczne niezależnie od użytego transportu.

Procedury tRPC można również udostępniać jako konwencjonalne endpointy REST za pomocą adaptera REST, aby zapewnić zgodność z klientami, które nie korzystają z tRPC.

tRPC działa jako middleware w Express, Fastify i Hono. W przypadku Next.js integruje się za pośrednictwem handlerów tras API. Starter create-t3-app (T3 Stack) łączy tRPC, Prisma, NextAuth i Tailwind w pełny szablon Next.js dla aplikacji full-stack.

T3 Stack jest najpopularniejszym punktem startowym dla tRPC i pokazuje wzorce gotowe do użycia w środowisku produkcyjnym.

Innym podejściem do bezpiecznego typowania REST jest zdefiniowanie schematów Zod, automatyczne wygenerowanie specyfikacji OpenAPI i wygenerowanie typów TypeScript na podstawie tej specyfikacji. Zapewnia to kontrakt API, z którego mogą korzystać klienci napisani w innych językach niż TypeScript.

tRPC jest prostsze, ale działa wyłącznie z TypeScript. OpenAPI+Zod zwiększa złożoność, ale tworzy publiczny kontrakt API. tRPC należy wybrać do wewnętrznej komunikacji TypeScript–TypeScript, a OpenAPI do publicznych API.

tRPC nie zastępuje REST, gdy potrzebne jest publiczne API używane przez podmioty zewnętrzne, klientów mobilnych napisanych w innym języku niż TypeScript lub partnerów wymagających stabilnego kontraktu z wersjonowaniem. Jest przeznaczone konkretnie dla monorepo TypeScript, w których ważne jest bezpieczeństwo typów w całym stosie.

Zrozumienie tego zakresu zapobiega przyjmowaniu tRPC w kontekstach, w których lepiej sprawdzi się REST lub GraphQL.

Uruchomienie npm create t3-app@latest tworzy szkielet projektu Next.js ze wstępnie skonfigurowanymi tRPC, Prisma, NextAuth.js, Tailwind CSS i TypeScript. Wygenerowany kod pokazuje strukturę routera, tworzenie kontekstu i konfigurację klienta.

Przeanalizowanie tego szkieletu to najszybszy sposób na zrozumienie, jak wszystkie elementy tRPC współdziałają w rzeczywistej aplikacji.

W jaki sposób tRPC współdzieli typy między serwerem a klientem bez generowania kodu?

tRPC rozwiązuje problem rozbieżności typów między klientem a serwerem TypeScript, bezpośrednio udostępniając typ TypeScript routera za pomocą importu, co eliminuje generowanie kodu. Działa w monorepozytoriach i integruje się z Next.js, Express, Fastify oraz Hono. T3 Stack (create-t3-app) to standardowy starter do zastosowań produkcyjnych.

tRPC jest przeznaczone wyłącznie dla TypeScript i najlepiej sprawdza się w wewnętrznych aplikacjach full-stack, a nie w publicznych interfejsach API.