tRPC:n käyttöönotto Reactin ja Next.js:n kanssa

Asentakaa @trpc/server ja @trpc/client tRPC:n ydinkirjastoja varten. Lisätkää @trpc/react-query React-koukkujen adapteriksi ja @tanstack/react-query niiden toiminnasta vastaavaksi peer-riippuvuudeksi.

Next.js:n API-reittien integrointiin ei tRPC:n uusimmissa versioissa tarvita erillistä adapteripakettia.

Luokaa server/trpc.ts-tiedosto ja kutsukaa initTRPC.create()-funktiota saadaksenne t-olion. Viekää t.router nimellä router, t.procedure nimellä publicProcedure ja t.mergeRouters apuohjelmana.

initTRPC-tehdas hyväksyy kontekstityypin geneerisenä tyyppiparametrina. Se määrittää, mitä tietoja on käytettävissä jokaisen proseduurin ctx-argumentissa.

Proseduuri määritetään ketjuttamalla .input(zodSchema).query(handler) tai .mutation(handler) publicProcedureen. Yksinkertainen hello-päätepiste voidaan määrittää näin: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Zod-skeema tarjoaa sekä TypeScript-tyypit että syötteen ajonaikaisen validoinnin.

Luokaa appRouter käyttämällä router()-funktiota: router({ hello: helloHandler, users: usersRouter }). Sisäkkäisten reitittimien avulla voitte järjestää proseduurit toimialueen mukaan (users, posts, comments) erillisiin tiedostoihin.

Viekää AppRouter-tyyppi: export type AppRouter = typeof appRouter. Asiakas tuo juuri tämän tyypin.

Luokaa app/api/trpc/[trpc]/route.ts (App Router) tai pages/api/trpc/[trpc].ts (Pages Router). Käyttäkää @trpc/server/adapters/fetch-paketin fetchRequestHandler-funktiota kaikkien tRPC-pyyntöjen käsittelyyn tämän yhden kaikkiin pyyntöihin vastaavan reitin kautta.

Välittäkää fetchRequestHandler-funktiolle reititin, createContext-funktio sekä request- ja response-oliot.

Luokaa utils/trpc.ts-tiedosto. Kutsukaa createTRPCReact()-funktiota tyypitetyn trpc-asiakasolion luomiseksi. Oliolla on ominaisuus jokaista reitittimen proseduuria varten, ja kukin ominaisuus tarjoaa React Query -koukut.

AppRouter-tyyppi tuodaan palvelintiedostosta. TypeScript seuraa import-ketjua ja tarkistaa kaikkien käyttötapojen tyypit.

Luokaa sovelluksen layoutissa tai _app.tsx-tiedostossa QueryClient-olio ja tRPC-asiakasolio käyttämällä seuraavaa määritystä: trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Ympäröikää komponenttipuu sekä trpc.Providerilla (tRPC-asiakkaan kanssa) että QueryClientProviderilla (QueryClientin kanssa). Molempia providereita tarvitaan.

Missä tahansa komponentissa voitte käyttää seuraavaa koodia: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). Hook on täysin tyypitetty: data on hello-proseduurin päätellyn paluuarvon tyyppi, ja syöteolio tarkistetaan Zod-skeemaa vasten.

Virheellisen syötetyypin välittäminen aiheuttaa TypeScriptin käännösvirheen, ei ajonaikaista virhettä.

Jotta tRPC toimii, asiakkaan on voitava tuoda tyyppejä palvelintiedostosta. Next.js-projektissa palvelimen ja asiakkaan koodi käännetään saman TypeScript-käännöksen yhteydessä, joten import-lauseet toimivat suoraan.

Erillisiä paketteja sisältävässä monorepossa määrittäkää TypeScript-projektiviittaukset tai tsconfig.json-tiedoston polkualiaset osoittamaan palvelinpakettiin.

tRPC-käsittelijä suoritetaan palvelimella (Next.js:n API-reittinä tai Edge Function -funktiona). tRPC-asiakas suoritetaan selaimessa. TypeScript käsittelee tyyppitason import-lauseet käännösaikana suorittamatta palvelinkoodia selaimessa.

Asiakas tuo vain AppRouter-tyypin, ei varsinaista toteutusta, joten palvelimen salaisuudet eivät päädy asiakkaan pakettiin.

Käynnistäkää Next.js:n kehityspalvelin ja avatkaa selaimen konsoli. trpc.hello.useQuery-kutsun pitäisi kirjata palvelimen vastaus. Tarkistakaa Network-välilehdeltä HTTP-pyyntö osoitteeseen /api/trpc/hello, jonka input on välitetty kyselyparametrina.

Oletusarvoinen httpBatchLink yhdistää useita samanaikaisia pyyntöjä yhdeksi HTTP-kutsuksi, minkä näkee verkon waterfall-näkymässä.

Asentakaa @trpc/server, @trpc/client, @trpc/react-query ja @tanstack/react-query. Alustakaa tRPC initTRPC.create()-kutsulla, määrittäkää proseduurit ja viekää AppRouter-tyyppi. Luokaa Next.js:n kaikkiin pyyntöihin vastaava API-reitti, määrittäkää TRPCProvider ja QueryClientProvider ja kutsukaa sen jälkeen proseduuria muodossa trpc.procedureName.useQuery().

TypeScript valvoo koko asiakkaan ja palvelimen välisen sopimuksen käännösaikana ilman koodin generointia.