Next.js App Router ile tRPC 11 Kurulumu: 2025 Rehberi

Modern web uygulamaları geliştirmek, hem performansı hem de geliştirici deneyimini bir arada sunan güçlü araçlar gerektirir. Peki, uçtan uca tip güvenliği sağlarken, API geliştirmenin karmaşıklığını minimuma indirmek mümkün mü? Bu kapsamlı rehberde, Next.js’in çığır açan App Router’ı ile tRPC 11’in nasıl entegre edileceğini adım adım inceleyeceğiz. Geliştirme sürecinizi baştan sona dönüştürecek bu güçlü kombinasyonla, 2025 ve sonrası için ölçeklenebilir ve bakımı kolay uygulamalar oluşturmanın kapılarını aralayın.

Geliştiriciler olarak, veri akışını yönetmek, istemci ve sunucu arasında güvenilir bir iletişim kurmak her zaman temel zorluklarımızdan biri olmuştur. Geleneksel yaklaşımlar çoğu zaman bu süreci gereksiz yere karmaşık hale getirirken, tRPC ve Next.js App Router’ın birleşimi adeta bir kurtarıcı gibi sahneye çıkıyor. Bu ikilinin sunduğu sinerji, hem geliştirme hızını artırıyor hem de hatalara karşı daha dirençli uygulamalar oluşturmanıza olanak tanıyor. Özellikle 2025 trendlerinde, hız ve güvenilirliğin yanı sıra geliştirici deneyimi de büyük bir önem taşıyor.

Geleneksel API Yaklaşımlarının Zorlukları Nelerdir?

API geliştirme dünyasında REST ve GraphQL gibi standartlar yıllardır hüküm sürmektedir. RESTful API’ler basitlikleri ve geniş destekleri sayesinde yaygınlaşmış olsa da, özellikle büyük ve karmaşık projelerde bazı dezavantajları barındırır. Örneğin, farklı kaynaklar için birden fazla endpoint tanımlamak gerekebilir ve bu da istemcinin birden çok istek yapmasına yol açabilir. Ayrıca, sunucu ve istemci arasındaki veri sözleşmelerinin manuel olarak senkronize edilmesi, tip güvenliği eksikliği nedeniyle run-time hatalarına davetiye çıkarabilir. Her iki tarafta da aynı veri yapısını sağlamak için genellikle ek araçlara veya manuel dokümantasyona ihtiyaç duyulur ki bu da geliştirme sürecini yavaşlatır ve hata payını artırır.

GraphQL ise bu sorunlara bir nebze çözüm getirir. İstemcinin tam olarak ihtiyacı olan veriyi tek bir istekte çekebilmesine olanak tanır, bu da fazla veri çekme (over-fetching) veya eksik veri çekme (under-fetching) sorunlarını ortadan kaldırır. Ancak GraphQL’in de kendine özgü bir öğrenme eğrisi ve karmaşıklığı vardır. Şema tanımı, resolver’lar ve istemci tarafında sorgu yazma pratikleri, projeye yeni başlayanlar için göz korkutucu olabilir. Üstelik, GraphQL ile bile uçtan uca tip güvenliği sağlamak için Apollo Client veya Relay gibi ek kütüphanelerle birlikte şema üretimi gibi adımlar atmak gerekebilir. Bu durum, özellikle küçük ve orta ölçekli projelerde veya prototipleme aşamasında gereksiz bir yük oluşturabilir. Her iki yaklaşım da, API katmanının ayrı bir kod tabanında yönetilmesini gerektirdiği için, istemci ve sunucu kodu arasında sürekli bir bağ kurma ve senkronizasyon ihtiyacını doğurur.

tRPC Nedir ve Ne Sunar?

tRPC, “TypeScript Remote Procedure Call”ın kısaltması olup, temelde TypeScript projeleri için tasarlanmış bir API geliştirme çerçevesidir. En büyük özelliği, istemci ile sunucu arasında otomatik olarak uçtan uca tip güvenliği sağlamasıdır. Yani, sunucunuzda bir API prosedürü tanımladığınızda, bu prosedürün tüm tip bilgileri otomatik olarak istemcinize aktarılır ve siz istemci tarafında bu prosedürü çağırırken IDE’niz size tüm tip hatalarını anında gösterir. Bu, geliştirme sürecindeki hataların büyük bir kısmını derleme zamanında yakalamanızı sağlar ve run-time hatalarının önüne geçer.

tRPC, HTTP katmanına herhangi bir şema veya kod üretimi gerektirmeden tam tip güvenliği getirir. Bu, geliştiricilerin sadece TypeScript yazarak güçlü ve güvenli API’lar oluşturabileceği anlamına gelir. “Zero-bundle” olması, istemciye tRPC’ye özgü ekstra bir çalışma zamanı kodu göndermediği anlamına gelir; sadece TypeScript tiplerini kullanır. Bu sayede, uygulamanızın başlangıç yükü (bundle size) minimumda kalır. Geliştirici deneyimi açısından ise tRPC adeta bir rüya gibidir. IDE’nizin sunduğu otomatik tamamlama (autocomplete) ve tip kontrolü sayesinde, sunucu tarafında tanımladığınız prosedürleri istemci tarafında kullanırken sanki yerel bir fonksiyon çağırıyormuş gibi hissedersiniz. Bu akıcı deneyim, API geliştirme sürecini çok daha hızlı, keyifli ve hatasız hale getirir. Sonuç olarak, tRPC, modern web geliştirmenin en büyük sorunlarından biri olan “client-server type mismatch” sorununa zarif ve etkili bir çözüm sunar.

Next.js App Router’ın Getirdikleri Nelerdir?

Next.js 13 ile tanıtılan App Router, React ekosisteminde bir dönüm noktası olarak kabul ediliyor. Bu yeni yönlendirme sistemi, React Server Components (RSC) mimarisini merkeze alarak performansı ve geliştirme deneyimini bir üst seviyeye taşıyor. App Router, sunucuda render edilen bileşenler (Server Components) ile istemcide render edilen bileşenleri (Client Components) bir araya getirerek, her iki tarafın avantajlarını kullanmanıza olanak tanır. Server Components, sunucuda çalışarak veri çekme, dosya erişimi veya veritabanı sorguları gibi işlemleri doğrudan yapabilir ve bu işlemleri istemciye göndermeden önce tamamlar. Bu sayede istemcinin JavaScript yükü azalır ve ilk sayfa yükleme süresi önemli ölçüde kısalır.

App Router ayrıca, layout.tsx, page.tsx, loading.tsx, error.tsx gibi dosya tabanlı özel bileşenler aracılığıyla sezgisel bir dosya sistemi yönlendirmesi sunar. Bu yapı, proje organizasyonunu basitleştirirken, routing mantığını daha okunur hale getirir. Sunucu Eylemleri (Server Actions) özelliği ise, istemciden doğrudan sunucuda çalıştırılabilir fonksiyonlar tanımlamanıza imkan tanır, bu da form gönderimleri ve veri mutasyonları gibi işlemleri daha güvenli ve tip-güvenli bir şekilde yapmanızı sağlar. Next.js App Router’ın getirdiği en büyük avantajlardan biri de, veri çekme mekanizmalarının optimize edilmiş olmasıdır. fetch API’sinin genişletilmiş özellikleri ve React’ın use hook’u sayesinde, asenkron veri çekme işlemleri Server Components içinde daha doğal ve verimli hale gelir. Tüm bu özellikler, Next.js App Router’ı modern, yüksek performanslı ve karmaşık web uygulamaları geliştirmek için ideal bir platform haline getirir.

tRPC 11 ve Next.js App Router Kurulumuna Adım Adım Başlangıç

tRPC 11’i Next.js App Router projenize entegre etmek, başlangıçta biraz göz korkutucu gelebilir; ancak doğru adımları izlediğinizde sürecin ne kadar mantıklı ve kolay olduğunu göreceksiniz. Amacımız, hem sunucu tarafında güçlü ve tip-güvenli bir API oluşturmak hem de bu API’yi Next.js’in modern sunucu ve istemci bileşen yapılarıyla sorunsuz bir şekilde kullanabilmek. Bu bölümde, projenizi nasıl oluşturacağınızdan tRPC bağımlılıklarını eklemeye, sunucu tarafı yapılandırmasından Next.js API rotalarını tanımlamaya kadar her adımı detaylıca ele alacağız. Bu adımlar, projenizin temelini sağlam bir şekilde atarak, ilerideki geliştirmeleriniz için güçlü bir zemin hazırlayacaktır. Unutmayın, doğru kurulum, sorunsuz bir geliştirme deneyiminin anahtarıdır.

Proje Oluşturma ve Temel Bağımlılıkları Yükleme

Öncelikle Next.js App Router destekli bir proje oluşturarak başlayacağız. Komut satırınızı açın ve aşağıdaki komutu çalıştırın:

  npx create-next-app@latest my-trpc-app

Bu komut size birkaç soru soracaktır. TypeScript'i ve App Router'ı etkinleştirdiğinizden emin olun:

• Would you like to use TypeScript? Yes
• Would you like to use ESLint? Yes
• Would you like to use Tailwind CSS? (Opsiyonel, ancak önerilir) Yes
• Would you like to use src/ directory? Yes
• Would you like to use App Router? (recommended) Yes
• Would you like to customize the default import alias? No

Proje oluşturulduktan sonra, projenizin dizinine gidin:

  cd my-trpc-app

Şimdi tRPC ve ilgili bağımlılıkları yükleyelim. tRPC, verimli veri çekme ve önbellekleme için @tanstack/react-query'den faydalanır. Ayrıca, API girdilerini doğrulamak için zod kütüphanesini kullanacağız:

  npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod

Bu bağımlılıklar, tRPC sunucunuzu kurmak, istemcinizle iletişim kurmak ve veri doğrulamayı sağlamak için gerekli temel yapı taşlarıdır. @trpc/client ve @trpc/react-query istemci tarafı için, @trpc/server ise sunucu tarafı için gereklidir. zod ise hem istemci hem de sunucu tarafında veri şemalarını tanımlayarak, API'nize gönderilen verilerin tip güvenliğini ve geçerliliğini sağlar. Bu, özellikle Next.js App Router ortamında, Server Actions veya Client Components aracılığıyla veri gönderirken kritik öneme sahiptir. Bağımlılıkları yükledikten sonra, projenizin geliştirme ortamı tRPC entegrasyonuna hazırdır.

Sunucu Tarafı tRPC Yapılandırması (server/trpc.ts ve server/routers/_app.ts)

tRPC'yi Next.js projenize entegre etmenin ilk adımı, sunucu tarafı yapılandırmasını oluşturmaktır. src dizini altında server adında yeni bir klasör oluşturalım. Bu klasör tRPC sunucumuzun mantığını barındıracak.

src/server/trpc.ts dosyası, tRPC sunucusunun temelini oluşturur. Burada, tRPC router'ımızı, context'i ve prosedürleri (query/mutation) başlatmak için gerekli araçları tanımlayacağız:

  <code>
    import { initTRPC } from '@trpc/server';
    import { createContext } from './context';

    /**
     * Bu, tRPC sunucumuzun her isteği için bağlam oluşturmak üzere kullanılacak işlevdir.
     * Genellikle, kimlik doğrulama, veritabanı bağlantısı gibi isteğe özel verileri içerir.
     */
    export const createTRPCContext = createContext;

    const t = initTRPC.context().create();

    /**
     * Public bir prosedür oluşturmak için kullanılan bir helper.
     * Bu prosedürlere herhangi bir giriş doğrulaması veya yetkilendirme uygulanmaz.
     */
    export const publicProcedure = t.procedure;
    export const router = t.router;
    export const middleware = t.middleware;
  code>

Burada initTRPC.context().create() ile tRPC örneğini başlatıyoruz. createTRPCContext fonksiyonu ise her istek için bir context oluşturacak. Bu context, veritabanı bağlantıları, kimlik doğrulama bilgileri gibi verilere erişim sağlamak için kullanılır. Şimdi src/server/context.ts dosyasını oluşturalım:

  <code>
    import { type inferAsyncReturnType } from '@trpc/server';
    import { type FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';

    /**
     * Sunucu tarafı isteği için oluşturulan bağlam.
     * Burada herhangi bir isteğe özel veri (örn: session, db) döndürebilirsiniz.
     */
    export const createContext = async (opts: FetchCreateContextFnOptions) => {
      return {
        // Örnek olarak, istek başlıklarına erişebilirsiniz
        headers: opts.req.headers,
      };
    };

    export type Context = inferAsyncReturnType;
  code>

Bu context.ts dosyası, tRPC prosedürleriniz içinde kullanabileceğiniz global verilere erişim sağlar. Örneğin, bir kullanıcının kimlik doğrulama bilgilerini burada işleyebilirsiniz.

Şimdi tRPC router'larımızı tanımlayalım. Router'lar, API prosedürlerinizi düzenlemenin ve gruplamanın bir yoludur. src/server/routers klasörünü oluşturun. İçine bir _app.ts dosyası ve örnek olarak post.ts dosyası ekleyelim.

src/server/routers/post.ts:

  <code>
    import { z } from 'zod';
    import { publicProcedure, router } from '../trpc';

    interface Post {
      id: string;
      title: string;
      content: string;
    }

    const posts: Post[] = [
      { id: '1', title: 'İlk Yazı', content: 'Bu bir deneme yazısıdır.' },
    ];

    export const postRouter = router({
      getPosts: publicProcedure
        .query(() => {
          return posts;
        }),

      getPostById: publicProcedure
        .input(z.object({ id: z.string() }))
        .query(({ input }) => {
          return posts.find(post => post.id === input.id);
        }),

      createPost: publicProcedure
        .input(z.object({
          title: z.string().min(5),
          content: z.string().min(10),
        }))
        .mutation(({ input }) => {
          const newPost: Post = {
            id: (posts.length + 1).toString(),
            ...input,
          };
          posts.push(newPost);
          return newPost;
        }),
    });
  code>

Bu postRouter, iki sorgu (getPosts, getPostById) ve bir mutasyon (createPost) tanımlıyor. zod kullanarak girdilerin doğruluğunu sağlıyoruz. Örneğin, createPost mutasyonunda title ve content alanlarının minimum uzunlukta olmasını zorunlu kılıyoruz. Bu, API'nize gelen verilerin her zaman beklendiği gibi olmasını garanti eder.

Son olarak, tüm router'ları birleştiren ana tRPC router'ını src/server/routers/_app.ts dosyasında oluşturalım:

  <code>
    import { router } from '../trpc';
    import { postRouter } from './post';

    export const appRouter = router({
      post: postRouter, // Post router'ı burada app router'a ekliyoruz
    });

    // İstemci tarafında kullanılacak app router tipi
    export type AppRouter = typeof appRouter;
  code>

_app.ts dosyası, tüm alt router'larınızı bir araya getiren ana tRPC router'ıdır. AppRouter tipi, istemci tarafında tip çıkarımı için kritik öneme sahiptir. Bu yapılandırma ile sunucu tarafı tRPC API'nizin temellerini atmış oldunuz. Artık Next.js App Router'ın API route'ları aracılığıyla bu API'yi dış dünyaya açabiliriz.

Next.js API Route Oluşturma (app/api/trpc/[trpc]/route.ts)

Next.js App Router'da, API rotaları da dosya sistemi tabanlıdır ve app/api dizini altında tanımlanır. tRPC sunucumuzu Next.js uygulamamızla entegre etmek için özel bir API route dosyası oluşturacağız. Bu dosya, tüm tRPC isteklerini tRPC sunucumuza yönlendirecek bir köprü görevi görecek.

src/app/api/trpc/[trpc]/route.ts yolunda bir dosya oluşturalım. Köşeli parantezler [trpc] dinamik bir rota segmenti olduğunu gösterir ve gelen tRPC isteklerinin farklı prosedürlere yönlendirilmesini sağlar.

  <code>
    import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
    import { appRouter, createTRPCContext } from '@/server'; // appRouter ve context'i içe aktarın

    const handler = (req: Request) =>
      fetchRequestHandler({
        endpoint: '/api/trpc',
        req,
        router: appRouter,
        createContext: createTRPCContext,
      });

    export { handler as GET, handler as POST };
  code>

Burada @trpc/server/adapters/fetch içindeki fetchRequestHandler'ı kullanıyoruz. Bu handler, gelen HTTP isteklerini alır, tRPC context'ini oluşturur ve isteği appRouter'daki ilgili tRPC prosedürüne yönlendirir. endpoint: '/api/trpc' tRPC istemcinizin istek göndereceği URL'i tanımlar. Son olarak, bu handler'ı hem GET hem de POST istekleri için dışa aktarıyoruz, çünkü tRPC hem sorgular (GET) hem de mutasyonlar (POST) için bu handler'ı kullanır. Bu adım, Next.js uygulamanızın tRPC API'nizle iletişim kurmasını sağlayan temel bağlantıyı kurar. Artık sunucu tarafınız hazır ve istemci tarafında bu API'yi kullanmaya başlayabiliriz.

export * from './trpc';export * from './context';export * from './routers/_app';

İstemci Tarafında tRPC Kullanımı ve Gerçek Dünya Senaryoları

Sunucu tarafı tRPC API'mizi başarıyla kurduğumuza göre, şimdi bu güçlü API'yi Next.js istemci bileşenlerimizde ve hatta sunucu bileşenlerimizde nasıl kullanacağımızı öğrenme zamanı. tRPC'nin gerçek gücü, istemci tarafında sunduğu uçtan uca tip güvenliği ve @tanstack/react-query ile entegrasyonu sayesinde ortaya çıkar. Bu bölüm, tRPC istemcisini nasıl yapılandıracağınızdan, veri çekme ve güncelleme işlemlerini nasıl yapacağınıza, ve küçük bir blog uygulaması üzerinden gerçek dünya senaryolarına kadar geniş bir yelpazeyi kapsayacak. Performans optimizasyonları ve önbellekleme stratejileri ile uygulamanızın hızını ve duyarlılığını nasıl artırabileceğinizi de detaylıca inceleyeceğiz.

tRPC İstemcisi Oluşturma ve Provider Yapılandırması

İstemci tarafında tRPC kullanabilmek için öncelikle bir tRPC istemcisi oluşturmalı ve bu istemciyi Next.js uygulamanızın kök bileşenine sağlamalısınız. Bunun için src/lib dizini altında trpc.ts adında bir dosya oluşturalım. Bu dosya, tRPC istemcisini yapılandıracak ve @tanstack/react-query ile entegrasyonu sağlayacaktır.

src/lib/trpc.ts:

  <code>
    import { httpBatchLink, loggerLink } from '@trpc/client';
    import { createTRPCReact } from '@trpc/react-query';
    import { type AppRouter } from '@/server/routers/_app';
    import superjson from 'superjson';

    export const trpc = createTRPCReact();

    // İstemci tarafında kullanmak üzere bir tRPC istemcisi oluşturun
    export const createClient = () =>
      trpc.createClient({
        transformer: superjson, // Tarih, Map, Set gibi tipleri serileştirmek için
        links: [
          loggerLink({
            enabled: (opts) =>
              process.env.NODE_ENV === 'development' ||
              (opts.direction === 'down' && opts.result instanceof Error),
          }),
          httpBatchLink({
            url: 'http://localhost:3000/api/trpc', // tRPC API endpoint'iniz
          }),
        ],
      });
  code>

Bu dosyada createTRPCReact() ile tRPC istemcisini oluşturuyoruz. AppRouter tipini sunucu tarafında tanımladığımız _app.ts dosyasından içe aktardığımız için, bu, istemci tarafında da otomatik tip güvenliği sağlar. createClient fonksiyonu, superjson kullanarak karmaşık tipleri serileştirir ve httpBatchLink ile API endpoint'ini belirtir. loggerLink ise geliştirme ortamında konsola tRPC isteklerini loglamaya yarar.

Şimdi bu istemciyi Next.js uygulamanızın app/layout.tsx dosyasında sağlayarak tüm bileşenlerinizin tRPC'ye erişmesini sağlayalım. src/app/layout.tsx dosyası tipik olarak tüm uygulamanızı sarmalayan kök layout'tur. Burada, @tanstack/react-query için QueryClientProvider ve tRPC için trpc.Provider'ı kullanacağız. Ancak bu provider'lar istemci bileşenleri olduğu için, bunları sarmalayan bir client component oluşturmamız gerekecek.

src/app/trpc-provider.tsx (Client Component):

  <code>
    'use client';

    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { loggerLink, httpBatchLink } from '@trpc/client';
    import { useState } from 'react';
    import { trpc } from '@/lib/trpc';
    import superjson from 'superjson';

    export function TRPCProvider({ children }: { children: React.ReactNode }) {
      const [queryClient] = useState(() => new QueryClient());
      const [trpcClient] = useState(() =>
        trpc.createClient({
          transformer: superjson,
          links: [
            loggerLink({
              enabled: (opts) =>
                process.env.NODE_ENV === 'development' ||
                (opts.direction === 'down' && opts.result instanceof Error),
            }),
            httpBatchLink({
              url: ${process.env.NEXT_PUBLIC_BASE_URL ?? 'http://localhost:3000'}/api/trpc,
            }),
          ],
        }),
      );

      return (
        
          
            {children}
          
        
      );
    }
  code>

Bu TRPCProvider bileşeni, QueryClient ve tRPC istemcisini useState hook'ları ile başlatır ve tüm alt bileşenlerine sağlar. Endpoint'i ortam değişkeni (NEXT_PUBLIC_BASE_URL) ile dinamik hale getirmeyi unutmayın. Şimdi src/app/layout.tsx dosyasını güncelleyelim:

  <code>
    import './globals.css';
    import { TRPCProvider } from './trpc-provider';

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        
          
            
              {children}
            
          
        
      );
    }
  code>

Bu adımlar, uygulamanızın tRPC istemcisini ve React Query'yi kullanmaya hazır olduğunu garanti eder. Artık herhangi bir client component'tan tRPC prosedürlerinizi çağırabilirsiniz.

Veri Çekme (Queries) ve Veri Güncelleme (Mutations)

tRPC, @tanstack/react-query ile entegre çalıştığı için, veri çekme ve güncelleme işlemleri oldukça sezgiseldir. useQuery hook'unu kullanarak veri çekebilir, useMutation hook'unu kullanarak veri güncelleyebilirsiniz. Bu hook'lar, yükleme durumları, hata yönetimi ve önbellekleme gibi birçok özelliği otomatik olarak ele alır.

Şimdi bir src/app/page.tsx dosyasında veya herhangi bir client component'ta tRPC prosedürlerimizi nasıl kullanacağımıza dair bir örnek oluşturalım.

src/app/page.tsx (Client Component olarak işaretleyelim):

  <code>
    'use client';

    import { trpc } from '@/lib/trpc';
    import { useState } from 'react';

    export default function HomePage() {
      // Tüm postları çekmek için useQuery kullanın
      const { data: posts, isLoading, error } = trpc.post.getPosts.useQuery();

      // Yeni post oluşturmak için useMutation kullanın
      const createPostMutation = trpc.post.createPost.useMutation({
        onSuccess: () => {
          alert('Post başarıyla oluşturuldu!');
          // Post listesini yenilemek için cache'i geçersiz kılın
          trpc.post.getPosts.invalidate(); 
        },
        onError: (err) => {
          alert(Hata oluştu: ${err.message});
        },
      });

      const [title, setTitle] = useState('');
      const [content, setContent] = useState('');

      const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        createPostMutation.mutate({ title, content });
        setTitle('');
        setContent('');
      };

      if (isLoading) return 
Yükleniyor...
;
      if (error) return 
Hata: {error.message}
;

      return (
        

          
Blog Yazıları

          {/* Yeni Post Oluşturma Formu */}
          

            
Yeni Post Oluştur
            

              Başlık:
              
                id="title"
                type="text"
                value={title}
                onChange={(e) => setTitle(e.target.value)}
                required
                style={{ width: '100%', padding: '8px', borderRadius: '4px', border: '1px solid #ddd' }}
              />
            
            

              İçerik:
                  <span>            id="content"</span>
    <span>            value={content}</span>
    <span>            onChange={(e) => setContent(e.target.value)}</span>
    <span>            required</span>
    <span>            rows={4}</span>
    <span>            style={{ width: '100%', padding: '8px', borderRadius: '4px', border: '1px solid #ddd' }}</span>
    <span>          /></span>
    <span>        </span>
            
                    style={{ padding: '10px 15px', borderRadius: '4px', border: 'none', backgroundColor: '#0070f3', color: 'white', cursor: 'pointer' }}>
              {createPostMutation.isLoading ? 'Oluşturuluyor...' : 'Post Oluştur'}
            
          

          {/* Post Listesi */}
          

            {posts?.map((post) => (
              

                
{post.title}
                
{post.content}
                ID: {post.id}
              
            ))}
          
        
      );
    }
  code>

Bu örnekte, trpc.post.getPosts.useQuery() ile tüm blog yazılarını çekiyoruz. isLoading ve error durumlarını kolayca yönetebiliyoruz. createPostMutation ise trpc.post.createPost.useMutation ile yeni bir yazı oluşturmak için kullanılıyor. onSuccess callback'inde trpc.post.getPosts.invalidate() çağırarak, yeni bir yazı eklendiğinde mevcut yazı listesinin önbelleğini geçersiz kılıyoruz ve böylece liste otomatik olarak güncelleniyor. Bu yaklaşım, kullanıcı arayüzünüzün her zaman güncel kalmasını sağlarken, gereksiz API isteklerini minimumda tutar. tRPC'nin en büyük avantajlarından biri de buradaki tip güvenliğidir; posts dizisinin elemanları otomatik olarak Post tipinde tanınır ve createPostMutation.mutate fonksiyonuna gönderilen title ve content alanlarının tipleri de sunucuda tanımladığımız zod şemasına uygun olmak zorundadır. Aksi takdirde, TypeScript derleyici hatası alırsınız, bu da run-time hatalarını önemli ölçüde azaltır.

Vaka Analizi: Küçük Bir Blog Uygulaması

Yukarıdaki kod bloğu aslında küçük bir blog uygulaması için temel CRUD operasyonlarının nasıl yapılacağına dair harika bir örnekti. Daha da ileri giderek, Next.js Server Components ile tRPC'yi nasıl kullanabileceğinizi gösteren bir senaryoya bakalım. Server Components doğrudan tRPC istemcisiyle etkileşime giremez, çünkü tRPC istemcisi browser API'leri gibi client-side ortam gerektirir. Ancak tRPC'nin gücünü Server Components'ta kullanmanın bir yolu var: Doğrudan sunucu tarafı router'ı çağırmak veya özel bir sunucu tarafı tRPC istemcisi oluşturmak.

src/server/trpc.server.ts adında bir dosya oluşturalım. Bu dosya, sadece sunucu bileşenlerinde kullanılacak bir tRPC istemcisi görevi görecek:

  <code>
    import { appRouter, createTRPCContext } from '@/server';

    // Server Components içinde tRPC prosedürlerini çağırmak için bir helper
    export const serverTrpc = appRouter.createCaller(createTRPCContext({
      // Server Components içinde Request nesnesine doğrudan erişim olmadığı için
      // boş bir başlık nesnesi gönderebilir veya ihtiyacınıza göre doldurabilirsiniz.
      req: new Request('http://localhost:3000'), 
      res: new Response(),
    }));
  code>

Burada appRouter.createCaller() kullanarak tRPC prosedürlerimizi doğrudan sunucu tarafında çağırabileceğimiz bir nesne oluşturuyoruz. createTRPCContext'e gönderilen req ve res nesneleri, Next.js'in API route handler'ında tRPC'nin beklediği yapıya uygun bir simülasyon sağlıyor.

Şimdi src/app/static-posts/page.tsx adında yeni bir Server Component oluşturalım ve burada serverTrpc'yi kullanarak gönderileri direkt sunucuda çekelim:

  <code>
    import { serverTrpc } from '@/server/trpc.server';
    import Link from 'next/link';

    export default async function StaticPostsPage() {
      const posts = await serverTrpc.post.getPosts();

      return (
        

          
Static Blog Yazıları (Server Component)
          
Bu gönderiler, sayfa sunucuda render edilirken doğrudan tRPC sunucusundan çekildi.
          

            {posts.map((post) => (
              

                
{post.title}
                
{post.content}
                /static-posts/${post.id}} style={{ color: '#0070f3', textDecoration: 'none' }}>
                  Devamını oku
                
              
            ))}
          
        
      );
    }
  code>

Bu StaticPostsPage bir Server Component olduğu için, async bir fonksiyon olarak tanımlanır ve await serverTrpc.post.getPosts() çağrısını doğrudan sunucuda yapar. Bu sayede, istemciye sadece HTML gönderilir ve ilk yükleme performansı artırılır. Bu yaklaşım, statik içerik veya ilk yüklemede gösterilmesi gereken veriler için idealdir. Server Components, tRPC ile birlikte kullanıldığında, uygulamanızın performansını ve kullanıcı deneyimini önemli ölçüde artırabilir.

Performans Optimizasyonları ve Önbellekleme

tRPC'nin @tanstack/react-query ile olan entegrasyonu, performans optimizasyonları ve önbellekleme konusunda size güçlü araçlar sunar. @tanstack/react-query (eski adıyla React Query), veri çekme, önbellekleme, senkronizasyon ve sunucu durumu yönetimini basitleştirir.

Otomatik Önbellekleme ve stale-while-revalidate:
useQuery hook'u, verileri otomatik olarak önbelleğe alır. Varsayılan olarak, bir sorgu "stale" (eskimiş) kabul edildikten sonra, kullanıcı arayüzünde mevcut önbelleğe alınmış veri gösterilirken arka planda yeni veri çekilir (stale-while-revalidate). Bu, kullanıcının her zaman anında bir yanıt almasını ve uygulamanın duyarlı kalmasını sağlar.

Manuel Önbellek Yönetimi:
Yukarıdaki createPostMutation örneğinde gördüğünüz gibi, bir mutasyon başarılı olduğunda trpc.post.getPosts.invalidate() çağırarak ilgili sorgunun önbelleğini manuel olarak geçersiz kılabiliriz. Bu, uygulamanın yeni verileri otomatik olarak tekrar çekmesini ve UI'ı güncellemesini sağlar.

Batching (Toplu İstekler):
tRPC'nin httpBatchLink özelliği, aynı render döngüsünde yapılan birden fazla tRPC isteğini tek bir HTTP isteğinde birleştirerek ağ trafiğini ve gecikmeyi azaltır. Bu, özellikle birçok farklı veriyi aynı anda çekmeniz gereken durumlarda performansı artırır.

Veri Prefetching:
Kullanıcı bir sayfayı ziyaret etmeden önce verileri önceden çekerek yükleme sürelerini daha da kısaltabilirsiniz. Next.js'in Link bileşeni, bağlantının üzerine gelindiğinde hedef sayfanın verilerini otomatik olarak önceden getirebilir. tRPC ve react-query ile bunu daha da optimize edebilirsiniz. Örneğin, bir liste sayfasında, detay sayfalarının verilerini kullanıcı listenin üzerine geldiğinde önceden çekmek mümkündür.

Mobil Uyumlu HTML ve Duyarlı Tasarım:
Performans sadece API hızından ibaret değildir, aynı zamanda kullanıcı arayüzünün (UI) duyarlılığı ve farklı cihazlarda iyi görünmesi de önemlidir. Next.js, mobil uyumlu tasarımlar için CSS modülleri veya Tailwind CSS gibi araçlarla kolayca entegre olur. Örneğin, CSS media query'lerini kullanarak farklı ekran boyutlarına göre stilleri ayarlayabilirsiniz:

  <code>
    /* src/app/globals.css */
    .container {
      padding: 20px;
    }

    @media (max-width: 768px) {
      .container {
        padding: 10px;
      }

      h1 {
        font-size: 1.5em;
      }

      ul li {
        margin-bottom: 5px;
        padding: 10px;
      }
    }
  code>

Bu basit CSS örneği, 768px genişliğin altındaki ekranlarda padding'i azaltır ve başlık boyutunu küçültür. tRPC ile hızlı ve tip-güvenli API'lar geliştirirken, Next.js'in sunduğu responsive tasarım yeteneklerini kullanarak kullanıcılarınıza tüm cihazlarda harika bir deneyim sunmayı unutmayın. Bu optimizasyonlar bir araya geldiğinde, uygulamanızın hem backend hem de frontend tarafında üst düzey performans sergilemesini sağlar.

Sonuç ve Sıkça Sorulan Sorular

Next.js App Router ile tRPC 11 entegrasyonu, modern web geliştirmenin en güçlü ve verimli yaklaşımlarından birini sunar. Bu rehber boyunca, tRPC'nin sunduğu uçtan uca tip güvenliğinden, Next.js App Router'ın getirdiği performans avantajlarına kadar birçok konuyu ele aldık. Proje oluşturma, sunucu ve istemci tarafı yapılandırmaları, veri çekme ve güncelleme işlemleri gibi pratik adımlarla, bu güçlü kombinasyonu kendi projelerinizde nasıl uygulayacağınızı öğrendiniz.

Geleceğe Yönelik Bakış

tRPC ve Next.js App Router'ın birlikte kullanımı, özellikle TypeScript ekosisteminde geliştirme yapanlar için oyunun kurallarını yeniden yazıyor. 2025 ve sonrasında, geliştirici deneyimi, performans ve güvenilirliğin önemi artmaya devam edecek. tRPC'nin sıfır çalışma zamanı ek yükü, otomatik tip güvenliği ve @tanstack/react-query ile kusursuz entegrasyonu, API katmanındaki birçok karmaşıklığı ortadan kaldırıyor. Next.js App Router ise React Server Components, Sunucu Eylemleri ve optimize edilmiş veri çekme mekanizmalarıyla, uygulamalarınızın hem hızlı hem de ölçeklenebilir olmasını sağlıyor.

Bu kombinasyon, daha az kodla daha fazlasını yapmanıza, hataları derleme zamanında yakalamanıza ve bu sayede daha sağlam ve bakımı kolay uygulamalar geliştirmenize olanak tanır. Özellikle büyük ekiplerde ve hızla büyüyen projelerde, tRPC'nin tip güvenliği, geliştiricilerin farklı modüller üzerinde paralel çalışırken tutarlılığı korumasına yardımcı olur. Next.js'in gelecekteki geliştirmeleriyle birlikte, bu entegrasyonun daha da sorunsuz ve güçlü hale gelmesi beklenmektedir. Bu teknoloji yığınını benimseyerek, web geliştirmenin geleceğine şimdiden yatırım yapmış olursunuz.

Sıkça Sorulan Sorular (SSS)