tRPC'nin Çözdüğü Sorun

TypeScript ile bir REST API oluşturduğunuzda yanıtın biçimini sunucu tanımlar. İstemci, eşleşen TypeScript türlerini elle oluşturmalıdır. API geliştikçe bu türler zamanla sapar ve türler ayrı paketlerde tanımlandığı için derleyici uyuşmazlığı yakalayamaz.

Sunucuda yeniden adlandırılan bir alan, istemcide sessiz bir çalışma zamanı hatasına dönüşür.

GraphQL, graphql-codegen gibi araçları kullanarak şemadan TypeScript türleri üreterek tür sapmasını çözer. Bu yaklaşım iyi çalışır, ancak ek karmaşıklık getirir: ayrı bir sorgu dili (GraphQL SDL), derleme işlem hattında bir kod üretme adımı ve şema yönetimi araçları.

Zaten GraphQL kullanan ekipler için codegen doğru çözümdür. GraphQL ek yükü olmadan tür güvenliği isteyen ekipler için tRPC bir alternatiftir.

tRPC'nin yaklaşımı olağanüstü derecede basittir: API yordamlarınızı sunucuda TypeScript işlevleri olarak tanımlayın, yönlendirici türünü dışa aktarın ve bu türü istemcide içe aktarın. Kod üretimi yoktur. Ayrı bir şema dili yoktur.

İstemci ile sunucu arasındaki sözleşmeyi derleme zamanında doğrudan TypeScript derleyicisi uygular.

tRPC, sunucu ve istemcinin türleri TypeScript içe aktarmalarıyla paylaşmasını gerektirir. Bu yaklaşım, sunucu ve istemcinin birbirinden içe aktarabilen ayrı paketler olduğu tek depolu bir yapıda (Turborepo, Nx, pnpm workspaces) doğal biçimde çalışır.

Arka uç ile ön yüz tamamen ayrıysa yönlendirici türlerini paylaşılan bir paket olarak yayımlamanız gerekir. Bu, bir yayımlama adımı ekler, ancak yine de codegen gerektirmez.

Sunucuda bir yönlendirici tanımlayıp türünü dışa aktarın: export type AppRouter = typeof appRouter. İstemcide bu türü içe aktarın ve tür bilgili bir istemci oluşturun: createTRPCReact(). İstemci, hangi yordamların bulunduğunu ve bunların girdi ve çıktı türlerini tam olarak bilir.

Sunucuda bir yordamı yeniden adlandırdığınızda istemcide hemen bir TypeScript hatası görüntülenir.

tRPC, TypeScript'in tür sistemini doğrudan kullandığı için düzenleyiciniz istemci tarafında yordam adları, girdi biçimleri ve dönüş türleri için tam otomatik tamamlama sağlar. Bir yordamı yeniden adlandırmak, kod tabanında elle arama ve değiştirme yapmak yerine bir TypeScript yeniden adlandırma düzenlemesidir.

Bu geliştirici deneyimi iyileştirmesi, uygulamada tRPC'nin en çok övülen özelliğidir.

tRPC, varsayılan olarak HTTP'yi aktarım mekanizması olarak kullanır. Her yordam çağrısı bir HTTP isteğidir. tRPC ayrıca abonelikler için WebSockets desteği sunar. Aktarım mekanizması uygulama ayrıntısıdır; aktarım mekanizması ne olursa olsun istemci API'si aynıdır.

tRPC kullanmayan istemcilerle uyumluluk için REST bağdaştırıcısını kullanarak tRPC yordamlarını geleneksel REST uç noktaları olarak da sunabilirsiniz.

tRPC, Express, Fastify ve Hono'da ara yazılım olarak çalışır. Next.js için API rota işleyicileri aracılığıyla bütünleşir. create-t3-app başlangıç projesi (T3 Stack), tRPC, Prisma, NextAuth ve Tailwind'i tam yığınlı bir Next.js şablonunda bir araya getirir.

T3 Stack, en popüler tRPC başlangıç noktasıdır ve üretim kullanımına hazır kalıpları gösterir.

Tür güvenli REST için başka bir yaklaşım da Zod şemaları tanımlamak, otomatik olarak bir OpenAPI belirtimi üretmek ve bu belirtimden TypeScript türleri oluşturmaktır. Bu yaklaşım, TypeScript kullanmayan istemcilerin de tüketebileceği bir API sözleşmesi sağlar.

tRPC daha basittir, ancak yalnızca TypeScript'e özgüdür. OpenAPI+Zod daha fazla karmaşıklık getirir, ancak herkese açık bir API sözleşmesi üretir. Şirket içi TypeScript'ten TypeScript'e iletişim için tRPC'yi, herkese açık API'ler için OpenAPI'yi seçin.

tRPC, üçüncü tarafların tükettiği herkese açık bir API'ye, TypeScript ile yazılmamış mobil istemcilere veya kararlı ve sürümlendirilmiş bir sözleşmeye ihtiyaç duyduğunuzda REST'in yerini tutmaz. tRPC özellikle tam yığın tür güvenliğine sahip TypeScript tek depolu yapıları için tasarlanmıştır.

Bu kapsamı anlamak, REST veya GraphQL'in daha uygun olduğu bağlamlarda tRPC'yi benimsemenizi önler.

npm create t3-app@latest çalıştırıldığında tRPC, Prisma, NextAuth.js, Tailwind CSS ve TypeScript önceden yapılandırılmış bir Next.js projesinin iskeletini oluşturur. Oluşturulan kod, yönlendirici yapısını, bağlam oluşturmayı ve istemci kurulumunu gösterir.

Bu iskeleti incelemek, tüm tRPC parçalarının gerçek bir uygulamada nasıl bir araya geldiğini anlamanın en hızlı yoludur.

tRPC, kod üretmeden sunucu ve istemci arasında türleri nasıl paylaşır?

tRPC, yönlendiricinin TypeScript türünü içe aktarma yoluyla doğrudan paylaşarak TypeScript istemcisi ile sunucusu arasındaki türlerin zamanla ayrışmasını önler ve kod üretimini ortadan kaldırır. Çoklu paket depolarında çalışır; Next.js, Express, Fastify ve Hono ile bütünleşir. T3 Stack (create-t3-app), üretim uygulamaları için standart başlangıç projesidir.

tRPC yalnızca TypeScript içindir ve herkese açık API'lerden ziyade şirket içi tam yığın uygulamalar için daha uygundur.