การตั้งค่า tRPC ร่วมกับ React และ Next.js

ติดตั้ง @trpc/server และ @trpc/client สำหรับแพ็กเกจหลักของ tRPC เพิ่ม @trpc/react-query เพื่อใช้เป็นตัวปรับใช้ฮุกของรีแอ็กต์ และเพิ่ม @tanstack/react-query เป็นส่วนพึ่งพาเพื่อนที่ขับเคลื่อนฮุกเหล่านี้

สำหรับการผสานการทำงานกับเส้นทาง API ของ Next.js ใน tRPC รุ่นล่าสุดไม่จำเป็นต้องติดตั้งแพ็กเกจตัวปรับใช้อื่นเพิ่มเติม

สร้างไฟล์ server/trpc.ts แล้วเรียก initTRPC.create() เพื่อรับออบเจ็กต์ t จากนั้นส่งออก t.router ในชื่อ router, t.procedure ในชื่อ publicProcedure และ t.mergeRouters เป็นยูทิลิตี

โรงงาน initTRPC รับชนิดข้อมูลเจเนริกของบริบท ซึ่งกำหนดว่าข้อมูลใดพร้อมใช้งานในอาร์กิวเมนต์ ctx ของกระบวนการทุกกระบวนการ

กำหนดกระบวนการด้วยการต่อ .input(zodSchema).query(handler) หรือ .mutation(handler) เข้ากับ publicProcedure สำหรับจุดปลายทาง hello แบบง่าย ให้ใช้ publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name)

สคีมา Zod จะจัดเตรียมทั้งชนิดข้อมูล TypeScript และการตรวจสอบความถูกต้องของข้อมูลเข้าขณะทำงาน

สร้าง appRouter โดยใช้ฟังก์ชัน router(): router({ hello: helloHandler, users: usersRouter }) เราเตอร์ซ้อนช่วยให้คุณจัดระเบียบกระบวนการตามขอบเขตงาน (ผู้ใช้ โพสต์ ความคิดเห็น) ไว้ในไฟล์แยกกันได้

ส่งออกชนิดข้อมูล AppRouter: export type AppRouter = typeof appRouter ชนิดข้อมูลนี้คือสิ่งที่ไคลเอ็นต์จะนำเข้า

สร้าง app/api/trpc/[trpc]/route.ts (เราเตอร์ของแอป) หรือ pages/api/trpc/[trpc].ts (เราเตอร์ของหน้า) ใช้ fetchRequestHandler จาก @trpc/server/adapters/fetch เพื่อจัดการคำขอ tRPC ทั้งหมดผ่านเส้นทางรวมนี้

ส่งเราเตอร์ ฟังก์ชัน createContext และออบเจ็กต์คำขอ/การตอบกลับให้กับ fetchRequestHandler

สร้างไฟล์ utils/trpc.ts เรียก createTRPCReact() เพื่อสร้างออบเจ็กต์ไคลเอ็นต์ trpc ที่มีชนิดข้อมูล ออบเจ็กต์นี้มีคุณสมบัติสำหรับทุกกระบวนการในเราเตอร์ของคุณ โดยแต่ละคุณสมบัติจะเปิดเผยฮุกของรีแอ็กต์คิวรี

การนำเข้าชนิดข้อมูล AppRouter มาจากไฟล์เซิร์ฟเวอร์ของคุณ และ TypeScript จะติดตามสายการนำเข้าเพื่อตรวจสอบการใช้งานทั้งหมด

ในโครงร่างแอปของคุณหรือ _app.tsx ให้สร้างอินสแตนซ์ QueryClient และอินสแตนซ์ไคลเอ็นต์ tRPC โดยใช้ trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] })

ครอบต้นไม้คอมโพเนนต์ของคุณด้วยทั้ง trpc.Provider (พร้อมไคลเอ็นต์ trpc) และ QueryClientProvider (พร้อม QueryClient) จำเป็นต้องใช้ตัวให้บริการทั้งสองรายการ

ในคอมโพเนนต์ใดก็ได้: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }) ฮุกนี้มีชนิดข้อมูลครบถ้วน: data คือชนิดข้อมูลผลลัพธ์ที่อนุมานได้จากกระบวนการ hello และออบเจ็กต์ข้อมูลเข้าจะถูกตรวจสอบชนิดข้อมูลตามสคีมา Zod

การส่งข้อมูลเข้าที่มีชนิดข้อมูลไม่ถูกต้องจะทำให้เกิดข้อผิดพลาดในการคอมไพล์ของ TypeScript ไม่ใช่ข้อผิดพลาดขณะทำงาน

เพื่อให้ tRPC ทำงานได้ ไคลเอ็นต์ต้องนำเข้าชนิดข้อมูลจากไฟล์เซิร์ฟเวอร์ ในโครงการ Next.js โค้ดฝั่งเซิร์ฟเวอร์และไคลเอ็นต์ใช้การคอมไพล์ TypeScript เดียวกัน ดังนั้นการนำเข้าจึงทำงานได้ทันที

ในโมโนเรโปที่มีแพ็กเกจแยกกัน ให้กำหนดการอ้างอิงโครงการของ TypeScript หรือชื่อแทนเส้นทางใน tsconfig.json เพื่อชี้ไปยังแพ็กเกจเซิร์ฟเวอร์

ตัวจัดการ tRPC ทำงานบนเซิร์ฟเวอร์ (ในฐานะเส้นทาง API ของ Next.js หรือฟังก์ชันขอบ) ส่วนไคลเอ็นต์ tRPC ทำงานในเบราว์เซอร์ TypeScript จะประเมินการนำเข้าระดับชนิดข้อมูลขณะสร้างโครงการ โดยไม่เรียกใช้โค้ดเซิร์ฟเวอร์ในเบราว์เซอร์

ไคลเอ็นต์จะนำเข้าเฉพาะชนิดข้อมูล AppRouter ไม่ใช่การนำไปใช้งานจริง ดังนั้นความลับของเซิร์ฟเวอร์จึงไม่รั่วไหลไปยังชุดรวมโค้ดของไคลเอ็นต์

เริ่มเซิร์ฟเวอร์พัฒนาของ Next.js แล้วเปิดคอนโซลของเบราว์เซอร์ การเรียก trpc.hello.useQuery ควรบันทึกการตอบกลับจากเซิร์ฟเวอร์ ตรวจสอบแท็บเครือข่ายเพื่อดูคำขอ HTTP ไปยัง /api/trpc/hello โดยมีข้อมูลเข้าที่รวมไว้เป็นพารามิเตอร์คิวรี

โดยค่าเริ่มต้น httpBatchLink จะรวมคำขอที่ทำพร้อมกันหลายรายการเป็นการเรียก HTTP ครั้งเดียว ซึ่งมองเห็นได้ในแผนภาพลำดับคำขอของเครือข่าย

ฟังก์ชันใดใช้เริ่มต้นอินสแตนซ์ tRPC และจัดเตรียมโรงงานสร้างเราเตอร์กับกระบวนการ

ติดตั้ง @trpc/server, @trpc/client, @trpc/react-query และ @tanstack/react-query เริ่มต้น tRPC ด้วย initTRPC.create() กำหนดกระบวนการ แล้วส่งออกชนิดข้อมูล AppRouter สร้างเส้นทางรวมของ API ใน Next.js ตั้งค่า TRPCProvider และ QueryClientProvider จากนั้นเรียกกระบวนการด้วย trpc.procedureName.useQuery()

TypeScript บังคับใช้สัญญาระหว่างไคลเอ็นต์กับเซิร์ฟเวอร์ทั้งหมดขณะคอมไพล์ โดยไม่ต้องสร้างโค้ด