Problemet, som tRPC løser

Når du bygger en REST API i TypeScript, definerer serveren svarstrukturen. Klienten skal manuelt oprette tilsvarende TypeScript-typer. Disse typer kommer ud af trit over tid, efterhånden som API'et udvikler sig, og compileren kan ikke opdage uoverensstemmelsen, fordi typerne er defineret i separate pakker.

Et felt, der omdøbes på serveren, bliver til en skjult runtime-fejl på klienten.

GraphQL løser typeafvigelser ved at generere TypeScript-typer fra skemaet ved hjælp af værktøjer som graphql-codegen. Det fungerer godt, men tilføjer kompleksitet: et separat forespørgselssprog (GraphQL SDL), et trin til kodegenerering i byggeforløbet og værktøjer til skemahåndtering.

For teams, der allerede har investeret i GraphQL, er kodegenerering det rigtige svar. For teams, der ønsker typesikkerhed uden GraphQL-omkostningerne, tilbyder tRPC et alternativ.

tRPC's tilgang er radikalt enkel: Definér dine API-procedurer på serveren som TypeScript-funktioner, eksportér routertypen, og importér den type på klienten. Ingen kodegenerering. Intet separat skemasprog.

TypeScript-compileren håndhæver selv kontrakten mellem klient og server på byggetidspunktet.

tRPC kræver, at serveren og klienten deler typer via TypeScript-importer. Det fungerer naturligt i et monorepo (Turborepo, Nx, pnpm workspaces), hvor serveren og klienten er separate pakker, der kan importere fra hinanden.

Hvis backend og frontend er fuldstændigt adskilt, skal du udgive routertyperne som en delt pakke. Det tilføjer et udgivelsestrin, men kræver stadig ingen kodegenerering.

På serveren definerer du en router og eksporterer dens type: export type AppRouter = typeof appRouter. På klienten importerer du den type og opretter en typesikker klient: createTRPCReact(). Klienten ved præcis, hvilke procedurer der findes, og hvilke typer deres inddata og uddata har.

Hvis du omdøber en procedure på serveren, vises der straks en TypeScript-fejl på klienten.

Fordi tRPC bruger TypeScript's typesystem direkte, giver din editor fuld autofuldførelse af procedurenavne, inddatastrukturer og returtyper på klientsiden. Omdøbning af en procedure er en TypeScript-rename-refaktorering, ikke en manuel søgning og erstatning på tværs af kodebasen.

Denne forbedring af udvikleroplevelsen er i praksis tRPC's mest roste funktion.

Som standard bruger tRPC HTTP som transportmekanisme. Hvert procedurekald er en HTTP-anmodning. tRPC understøtter også WebSockets til abonnementer. Transportmekanismen er en implementeringsdetalje; klientens API er identisk uanset transportmekanismen.

Du kan også eksponere tRPC-procedurer som almindelige REST-endepunkter ved hjælp af REST-adapteren, så de er kompatible med klienter, der ikke bruger tRPC.

tRPC fungerer som middleware i Express, Fastify og Hono. I Next.js integreres det via håndteringsfunktioner til API-ruter. Startskabelonen create-t3-app (T3 Stack) samler tRPC, Prisma, NextAuth og Tailwind i en fuldstack-Next.js-skabelon.

T3 Stack er det mest populære udgangspunkt for tRPC og viser produktionsklare mønstre.

En anden typesikker REST-tilgang er at definere Zod-skemaer, generere en OpenAPI-specifikation automatisk og generere TypeScript-typer fra specifikationen. Det giver en API-kontrakt, som klienter, der ikke er skrevet i TypeScript, kan bruge.

tRPC er enklere, men kun til TypeScript. OpenAPI+Zod tilføjer kompleksitet, men producerer en offentlig API-kontrakt. Vælg tRPC til intern kommunikation fra TypeScript til TypeScript; vælg OpenAPI til offentlige API'er.

tRPC er ikke en erstatning for REST, når du har brug for en offentlig API, der bruges af tredjeparter, mobilklienter, som ikke er skrevet i TypeScript, eller partnere, der har brug for en stabil, versionsstyret kontrakt. Det er specifikt beregnet til TypeScript-monorepoer med typesikkerhed i hele stakken.

Hvis du forstår dette anvendelsesområde, undgår du at tage tRPC i brug i sammenhænge, hvor REST eller GraphQL passer bedre.

Hvis du kører npm create t3-app@latest, opretter det grundstrukturen til et Next.js-projekt med tRPC, Prisma, NextAuth.js, Tailwind CSS og TypeScript forudkonfigureret. Den genererede kode viser routerstrukturen, oprettelsen af konteksten og opsætningen af klienten.

Ved at studere denne grundstruktur får du den hurtigste vej til at forstå, hvordan alle tRPC-delene passer sammen i en rigtig applikation.

tRPC løser uoverensstemmelser mellem typer på TypeScript-klienten og -serveren ved at dele routerens TypeScript-type direkte via import, så kodegenerering bliver overflødig. Det fungerer i monorepoer og integreres med Next.js, Express, Fastify og Hono. T3 Stack (create-t3-app) er det almindelige startprojekt til produktion.

tRPC fungerer kun med TypeScript og er bedst egnet til interne full-stack-applikationer, ikke til offentlige API'er.