إعداد tRPC مع React وNext.js

ثبّت @trpc/server و@trpc/client لاستخدام حزمتَي tRPC الأساسيتين. أضف @trpc/react-query لتوفير محوّل خطافات React، وأضف @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. ولإنشاء نقطة نهاية بسيطة للتحية، استخدم: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

يوفّر مخطط Zod أنواع TypeScript والتحقق من صحة المدخلات أثناء وقت التشغيل معًا.

أنشئ appRouter باستخدام الدالة router(): router({ hello: helloHandler, users: usersRouter }). تتيح لك الموجّهات المتداخلة تنظيم الإجراءات حسب المجال، مثل users وposts وcomments، في ملفات منفصلة.

صدّر نوع AppRouter: export type AppRouter = typeof appRouter. هذا هو النوع الذي سيستورده العميل.

أنشئ app/api/trpc/[trpc]/route.ts (موجّه App Router) أو pages/api/trpc/[trpc].ts (موجّه Pages Router). استخدم fetchRequestHandler من @trpc/server/adapters/fetch لمعالجة جميع طلبات tRPC عبر هذا المسار الشامل الواحد.

مرّر الموجّه ودالة createContext وكائنَي الطلب والاستجابة إلى fetchRequestHandler.

أنشئ الملف utils/trpc.ts. استدعِ createTRPCReact() لإنشاء كائن عميل trpc المعرّف بالأنواع. يحتوي هذا الكائن على خاصية لكل إجراء في الموجّه، وتوفّر كل خاصية خطافات React Query.

يُستورَد النوع 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 أو Edge Function. ويعمل عميل tRPC في المتصفح. يقيّم TypeScript الاستيرادات على مستوى الأنواع أثناء وقت البناء، من دون تنفيذ رمز الخادم في المتصفح.

يُستورَد نوع AppRouter فقط على العميل، وليس التنفيذ الفعلي، لذلك لا تتسرّب أسرار الخادم إلى حزمة العميل.

شغّل خادم التطوير في Next.js وافتح وحدة تحكم المتصفح. من المفترض أن يسجّل استدعاء trpc.hello.useQuery استجابة الخادم. تحقّق من علامة تبويب Network لرؤية طلب 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 عقد الخادم والعميل بالكامل أثناء وقت التجميع، من دون توليد التعليمات البرمجية.