Ulaşım
- Adres:Batıkent Mh. 8910 Sk. 6. Etap 1H No: 18 Yeni Toki Eyyübiye / Şanlıurfa (Yeni Alım Satım Karşısı)
- Telefon:0 (545) 528 88 93
- eMail: info@alestaweb.com
tRPC v11, TypeScript ekosisteminin en heyecan verici kütüphanelerinden biri olarak end-to-end tip güvenliği sağlayan API geliştirmeyi tamamen yeniden tanımlıyor. tRPC type-safe API yaklaşımıyla REST veya GraphQL şema tanımlamalarına gerek kalmadan, istemci ve sunucu arasındaki tam TypeScript tip senkronizasyonunu sağlayabilirsiniz. Alesta Web ekibi olarak tRPC v11'i derinlemesine inceledik ve bu kapsamlı rehberi hazırladık!
tRPC (TypeScript Remote Procedure Call), REST API endpoint'leri veya GraphQL şemaları yazmadan istemci ve sunucu arasında tam tip güvenli iletişim kurmanızı sağlayan bir kütüphanedir. tRPC type-safe API yaklaşımı sayesinde API çağrılarında derleme zamanında tip hataları yakalanır.
tRPC v11, önceki versiyonlara kıyasla önemli yenilikler getirdi. Alesta Web web projelerinde tRPC v11 kullanımı hız ve tip güvenliği konusunda belirgin avantajlar sağlamaktadır.
initTRPC ile daha temiz router kurulumutRPC v11, REST API'nin esnekliğini GraphQL'in tip güvenliğiyle birleştiriyor ancak şema yazma gerektirmiyor. Alesta Web projelerinde dahili API'ler için tRPC v11, harici API'ler için REST tercih ediyoruz.
tRPC v11'i Next.js App Router ile kurmak adım adım yapılması gereken bir süreçtir. Alesta Web projelerinde standart kurulum şablonunu paylaşıyoruz.
# Next.js projesi oluştur (zaten varsa atlayın)
npx create-next-app@latest my-app --typescript --app
cd my-app
# tRPC v11 bağımlılıkları
npm install @trpc/server@11 @trpc/client@11 @trpc/react-query@11 @trpc/next@11
# React Query (tRPC v11 için v5 gerekli)
npm install @tanstack/react-query@5
# Input validation için Zod
npm install zod
# (Opsiyonel) SuperJSON - tarih ve Map/Set serializasyonu için
npm install superjsonsrc/
├── app/
│ ├── api/
│ │ └── trpc/
│ │ └── [trpc]/
│ │ └── route.ts # tRPC HTTP handler
│ └── layout.tsx
├── server/
│ ├── trpc.ts # tRPC init
│ ├── routers/
│ │ ├── _app.ts # Ana router
│ │ ├── user.ts
│ │ └── post.ts
│ └── context.ts # Request context
└── utils/
└── trpc.ts # İstemci tarafı helperimport { initTRPC, TRPCError } from "@trpc/server";
import superjson from "superjson";
import { ZodError } from "zod";
import type { Context } from "./context";
const t = initTRPC.context().create({
transformer: superjson,
errorFormatter({ shape, error }) {
return {
...shape,
data: {
...shape.data,
zodError:
error.cause instanceof ZodError ? error.cause.flatten() : null,
},
};
},
});
// Router ve procedure factory'leri
export const router = t.router;
export const publicProcedure = t.procedure;
// Auth middleware
const enforceUserIsAuthed = t.middleware(({ ctx, next }) => {
if (!ctx.session?.user) {
throw new TRPCError({ code: "UNAUTHORIZED" });
}
return next({ ctx: { ...ctx, session: ctx.session } });
});
export const protectedProcedure = t.procedure.use(enforceUserIsAuthed); tRPC v11'in çekirdeği router ve procedure kavramlarıdır. tRPC type-safe API yapısında her procedure, hem istemci hem sunucu tarafında tam olarak tiplenmiş olur.
import { z } from "zod";
import { router, publicProcedure, protectedProcedure } from "../trpc";
export const userRouter = router({
// Query procedure - veri okuma
getById: publicProcedure
.input(z.object({ id: z.string().uuid() }))
.query(async ({ input, ctx }) => {
const user = await ctx.db.user.findUnique({
where: { id: input.id },
select: { id: true, name: true, email: true, createdAt: true }
});
if (!user) {
throw new TRPCError({ code: "NOT_FOUND", message: "Kullanıcı bulunamadı" });
}
return user;
}),
// Mutation procedure - veri yazma
create: protectedProcedure
.input(z.object({
name: z.string().min(2).max(100),
email: z.string().email(),
role: z.enum(["admin", "user", "editor"]).default("user")
}))
.mutation(async ({ input, ctx }) => {
const user = await ctx.db.user.create({ data: input });
return { success: true, userId: user.id };
}),
// Sayfalandırılmış liste
list: publicProcedure
.input(z.object({
page: z.number().min(1).default(1),
limit: z.number().min(1).max(100).default(20)
}))
.query(async ({ input, ctx }) => {
const skip = (input.page - 1) * input.limit;
const [users, total] = await ctx.db.$transaction([
ctx.db.user.findMany({ skip, take: input.limit }),
ctx.db.user.count()
]);
return { users, total, pages: Math.ceil(total / input.limit) };
}),
});import { router } from "../trpc";
import { userRouter } from "./user";
import { postRouter } from "./post";
export const appRouter = router({
user: userRouter,
post: postRouter,
});
// Type export (istemci tarafında kullanılacak)
export type AppRouter = typeof appRouter;tRPC v11 router yapısı kuruldu. AppRouter tipi istemci tarafına export edildiğinde tam tip senkronizasyonu sağlanır. Alesta Web projelerinde bu yapıyı monorepo içinde hem frontend hem backend için kullanıyoruz.
tRPC v11, React Query v5 ile sorunsuz entegrasyon sağlar. tRPC type-safe API'nizi React componentlerinden çağırmak son derece basittir.
import { createTRPCReact } from "@trpc/react-query";
import type { AppRouter } from "../server/routers/_app";
export const trpc = createTRPCReact(); "use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { httpBatchLink } from "@trpc/client";
import { trpc } from "../utils/trpc";
import superjson from "superjson";
import { useState } from "react";
export default function TRPCProvider({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(() => new QueryClient());
const [trpcClient] = useState(() =>
trpc.createClient({
links: [
httpBatchLink({
url: "/api/trpc",
transformer: superjson,
}),
],
})
);
return (
{children}
);
}"use client";
import { trpc } from "../utils/trpc";
export function UserProfile({ userId }: { userId: string }) {
// Tam tip güvenli query - tRPC type-safe API
const { data, isLoading, error } = trpc.user.getById.useQuery({ id: userId });
// Mutation
const createUser = trpc.user.create.useMutation({
onSuccess: (data) => {
console.log("Oluşturuldu:", data.userId);
}
});
if (isLoading) return Yükleniyor...;
if (error) return Hata: {error.message};
return (
{data?.name}
{data?.email}
);
}tRPC v11, Zod ile mükemmel entegrasyon sağlar. tRPC type-safe API'lerde input validation hem sunucu güvenliği hem de istemci tip güvenliği açısından kritiktir.
import { z } from "zod";
import { router, publicProcedure } from "../trpc";
// Karmaşık input şeması
const createProductInput = z.object({
name: z.string().min(3, "En az 3 karakter").max(200),
price: z.number().positive("Fiyat pozitif olmalı").multipleOf(0.01),
category: z.enum(["electronics", "clothing", "food", "software"]),
tags: z.array(z.string()).max(10).optional(),
images: z.array(z.string().url()).min(1).max(5),
metadata: z.record(z.string(), z.unknown()).optional(),
publishAt: z.date().min(new Date(), "Geçmiş tarih seçilemez").optional()
});
export const productRouter = router({
create: publicProcedure
.input(createProductInput)
.mutation(async ({ input }) => {
// input tam olarak tiplenmiş
// input.price tipi: number
// input.category tipi: "electronics" | "clothing" | "food" | "software"
console.log("Ürün oluşturuluyor:", input.name);
return { success: true };
}),
});tRPC v11 ile Zod hatalar otomatik olarak istemciye iletilir ve React Query error state'inde Zod validation mesajlarına erişilebilir. Alesta Web form geliştirmelerinde bu özelliği yoğun kullanıyoruz.
tRPC v11'de hata yönetimi ve middleware yapısı, production-ready uygulamalar için güçlü araçlar sunar.
import { initTRPC } from "@trpc/server";
const t = initTRPC.create();
// Logging middleware
const loggerMiddleware = t.middleware(async ({ path, type, next }) => {
const start = Date.now();
const result = await next();
const ms = Date.now() - start;
console.log(`[tRPC] ${type} ${path} - ${ms}ms - ${result.ok ? "OK" : "ERR"}`);
return result;
});
// Rate limiting middleware
const rateLimitMiddleware = t.middleware(async ({ ctx, next }) => {
const ip = ctx.req.headers["x-forwarded-for"] || "unknown";
// Rate limit logic
return next();
});
export const publicProcedure = t.procedure
.use(loggerMiddleware)
.use(rateLimitMiddleware);tRPC v11 ile REST API arasındaki farkları anlamak, hangi projeye hangisinin uygun olduğuna karar vermenizi sağlar. Alesta Web olarak her iki yaklaşımı da aktif kullanıyoruz.
/*
Özellik | tRPC v11 | REST API
---------------------|-------------------|------------------
Tip güvenliği | Otomatik (E2E) | Manuel (OpenAPI)
Şema tanımı | Gerekmez | Gerekir
İstemci kodu | Otomatik üretilir | Manuel yazılır
Harici erişim | Zor | Kolay
Öğrenme eğrisi | Orta | Düşük
Ekosistem | TypeScript-only | Dil bağımsız
Performans | HTTP batching | Standart
GraphQL ile karşıl. | Daha basit | -
Alesta Web kullanımı | İç API'ler | Harici API'ler
*/tRPC v11, TypeScript dışındaki dillerde kullanılamaz. Eğer API'nize üçüncü parti uygulamalar bağlanacaksa REST veya GraphQL tercih edin. Alesta Web harici entegrasyonlar için REST API sunmaya devam ediyor.
tRPC v11 uygulamasını production'a almak için birkaç kritik adım gereklidir.
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "../../../../server/routers/_app";
import { createContext } from "../../../../server/context";
const handler = (req: Request) =>
fetchRequestHandler({
endpoint: "/api/trpc",
req,
router: appRouter,
createContext,
onError: ({ path, error }) => {
if (error.code === "INTERNAL_SERVER_ERROR") {
// Alesta Web - production hata loglama
console.error(`[tRPC ERROR] ${path}:`, error);
}
}
});
export { handler as GET, handler as POST };tRPC v11 uygulamanız production'a hazır! Alesta Web olarak tRPC type-safe API geliştirme konusunda danışmanlık için alestaweb.com'u ziyaret edin.
tRPC v11 ile TypeScript end-to-end tip güvenliği artık elinizin altında! Alesta Web ekibi olarak tRPC type-safe API yaklaşımının modern web geliştirme süreçlerini nasıl dönüştürdüğünü her gün yaşıyoruz. Bu rehberdeki adımları izleyerek Next.js + tRPC v11 stack'inizle üretken ve hatasız API'ler geliştirebilirsiniz.
Faydalı Linkler:
© 2026 AlestaWeb - Tüm hakları saklıdır.