Menyiapkan tRPC dengan React dan Next.js

Instal @trpc/server dan @trpc/client untuk paket inti tRPC. Tambahkan @trpc/react-query sebagai adaptor kait React dan @tanstack/react-query sebagai dependensi rekan yang mendukung kait tersebut.

Untuk integrasi rute API Next.js, versi terbaru tRPC tidak memerlukan paket adaptor tambahan.

Buat file server/trpc.ts dan panggil initTRPC.create() untuk mendapatkan objek t. Ekspor t.router sebagai router, t.procedure sebagai publicProcedure, dan t.mergeRouters sebagai utilitas.

Pabrik initTRPC menerima generik tipe konteks yang menentukan data apa yang tersedia dalam argumen ctx setiap prosedur.

Prosedur didefinisikan dengan merangkai .input(zodSchema).query(handler) atau .mutation(handler) ke publicProcedure. Untuk titik akhir sapaan sederhana: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Skema Zod menyediakan tipe TypeScript sekaligus validasi saat waktu proses untuk masukan tersebut.

Buat appRouter menggunakan fungsi router(): router({ hello: helloHandler, users: usersRouter }). Router bertingkat memungkinkan Anda mengatur prosedur berdasarkan domain (pengguna, postingan, komentar) ke dalam file terpisah.

Ekspor tipe AppRouter: export type AppRouter = typeof appRouter. Tipe inilah yang akan diimpor oleh klien.

Buat app/api/trpc/[trpc]/route.ts (App Router) atau pages/api/trpc/[trpc].ts (Pages Router). Gunakan fetchRequestHandler dari @trpc/server/adapters/fetch untuk menangani semua permintaan tRPC melalui satu rute penangkap-semua.

Teruskan router, fungsi createContext, serta objek permintaan/respons ke fetchRequestHandler.

Buat file utils/trpc.ts. Panggil createTRPCReact() untuk membuat objek klien trpc yang memiliki tipe. Objek ini memiliki properti untuk setiap prosedur di router Anda, dan setiap properti menyediakan kait React Query.

Impor tipe AppRouter berasal dari file server; TypeScript mengikuti rantai impor untuk memvalidasi semua penggunaannya.

Di tata letak aplikasi atau _app.tsx Anda, buat instans QueryClient dan instans klien tRPC menggunakan trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Bungkus pohon komponen Anda dengan trpc.Provider (menggunakan klien trpc) dan QueryClientProvider (menggunakan QueryClient). Kedua penyedia tersebut diperlukan.

Di komponen mana pun: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). Kait ini memiliki tipe lengkap: data adalah tipe hasil yang disimpulkan dari prosedur hello, dan objek masukan diperiksa tipenya berdasarkan skema Zod.

Memberikan tipe masukan yang salah akan menghasilkan kesalahan kompilasi TypeScript, bukan kesalahan saat waktu proses.

Agar tRPC dapat berfungsi, klien harus dapat mengimpor tipe dari file server. Dalam proyek Next.js, kode server dan klien menggunakan kompilasi TypeScript yang sama, sehingga impor dapat langsung digunakan.

Dalam monorepo dengan paket terpisah, konfigurasikan referensi proyek TypeScript atau alias jalur di tsconfig.json agar mengarah ke paket server.

Penangan tRPC berjalan di server (sebagai rute API Next.js atau Edge Function). Klien tRPC berjalan di peramban. TypeScript mengevaluasi impor tingkat tipe pada waktu build tanpa menjalankan kode server di peramban.

Hanya tipe AppRouter yang diimpor oleh klien, bukan implementasi sebenarnya, sehingga rahasia server tidak bocor ke bundel klien.

Jalankan server pengembangan Next.js dan buka konsol peramban. Panggilan trpc.hello.useQuery seharusnya mencatat respons server. Periksa tab Network untuk melihat permintaan HTTP ke /api/trpc/hello dengan masukan yang dikirim sebagai parameter kueri.

Secara bawaan, httpBatchLink menggabungkan beberapa permintaan serentak menjadi satu panggilan HTTP, yang terlihat pada urutan permintaan jaringan.

Fungsi apa yang menginisialisasi instans tRPC dan menyediakan pabrik router serta prosedur?

Instal @trpc/server, @trpc/client, @trpc/react-query, dan @tanstack/react-query. Inisialisasi tRPC dengan initTRPC.create(), definisikan prosedur, lalu ekspor tipe AppRouter. Buat rute penangkap-semua API Next.js, siapkan TRPCProvider dan QueryClientProvider, lalu panggil prosedur dengan trpc.procedureName.useQuery().

TypeScript menegakkan seluruh kontrak antara klien dan server pada waktu kompilasi tanpa pembuatan kode.