TanStack Start v1 Rehberi 2026: Type-Safe React Framework, Server Functions ve Next.js Karşılaştırması

TanStack Start Nedir? (What is TanStack Start)

TanStack Start, TanStack ekosisteminin (TanStack Query, Table, Router ile tanıdığınız ekip) tam yığın React çerçevesi. Temeli üç parça üzerine oturuyor:

• TanStack Router — tip güvenli yönlendirme motoru
• Vite (ya da Rsbuild) — geliştirme sunucusu ve derleyici
• Nitro — sunucu katmanı; farklı platformlara dağıtım imkânı

Sunduğu özellikler listesi tanıdık gelecek: tam doküman sunucu tarafı render (full-document SSR), streaming, server functions, API rotaları, middleware ve tam yığın derleme. Peki farkı ne?

Bu tercih hem gücü hem de sınırı. React Server Components'ın getirdiği sunucu tarafı veri erişimi kolaylığını istiyorsanız TanStack Start size bunu (henüz) tam olarak vermez. Buna karşılık, RSC'nin getirdiği karmaşayı da yaşamazsınız.

Sürüm durumu

TanStack Start v1.0 sürümü 2026'nın ilk çeyreğinde yayınlandı ve üretime hazır kabul ediliyor. Resmî dokümantasyonun bazı sayfaları hâlâ sürüm adayı (release candidate) dönemine ait ifadeler taşıyor; bu bir tutarsızlık gibi görünse de API kararlı durumda. Alesta Web olarak değerlendirmemiz şu: gerçek uygulamalar için yeterince olgun, ama ekosistem Next.js kadar geniş değil.

Kurulum ve İlk Proje (Installation and First App)

# Resmi CLI ile
npx @tanstack/cli@latest create

# Sorulara cevap verin: proje adi, TypeScript, paket yoneticisi
cd projem
npm install
npm run dev

Geliştirme sunucusu ayağa kalktığında Vite'ın bilindik hızını görürsünüz. Soğuk başlangıç (cold start) genellikle bir saniyenin altında.

src/
  routes/
    __root.tsx          # kok layout
    index.tsx           # /
    posts.tsx           # /posts  (layout)
    posts.index.tsx     # /posts
    posts.$postId.tsx   # /posts/:postId
  server/
    db.ts
  router.tsx
vite.config.ts

Dosya adlandırması nokta ile ayrılıyor: posts.$postId.tsx dosyası /posts/:postId rotasına karşılık geliyor. $ işareti dinamik parametreyi belirtir. Klasör tabanlı yapı da destekleniyor; tercih size kalmış.

Tip Güvenli Yönlendirme (Type-Safe Routing)

Framework'ün asıl iddiası burada. Rotalarınız derleme zamanında doğrulanıyor. Yani $postId yerine yanlışlıkla $postID yazarsanız, siteyi açıp 404 görmeden önce editörünüz uyarıyor.

// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    return fetchPost(params.postId)   // params.postId: string
  },
  component: PostPage,
})

function PostPage() {
  const post = Route.useLoaderData()  // tipi otomatik cikarilir
  const { postId } = Route.useParams()

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  )
}

Route.useLoaderData() çağrısının dönüş tipi, loader fonksiyonunuzun dönüşünden otomatik türetilir. Elle tip yazmanıza gerek yok; as Post gibi zorlamalara da.

Arama parametreleri (search params) de tip güvenli

Bu, çoğu framework'ün zayıf bıraktığı bir alan. TanStack Start'ta URL sorgu parametreleri şema ile doğrulanır:

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const searchSchema = z.object({
  page: z.number().int().min(1).catch(1),
  sirala: z.enum(['tarih', 'baslik']).catch('tarih'),
})

export const Route = createFileRoute('/posts/')({
  validateSearch: searchSchema,
  component: PostList,
})

function PostList() {
  const { page, sirala } = Route.useSearch()  // number, 'tarih'|'baslik'
  // ...
}

Tip güvenli bağlantılar

import { Link } from '@tanstack/react-router'

<Link to="/posts/$postId" params={{ postId: '42' }}>
  Yaziyi ac
</Link>

// Olmayan bir rota yazarsaniz: DERLEME HATASI
// Eksik parametre birakirsaniz: DERLEME HATASI

Server Functions: RPC Gibi Sunucu Kodu (Server Functions)

Sunucuda çalışması gereken kodu istemciden doğrudan çağırıyormuş gibi yazarsınız. Framework araya HTTP katmanını kendisi koyar.

import { createServerFn } from '@tanstack/react-start'
import { db } from '~/server/db'

export const getPosts = createServerFn({ method: 'GET' })
  .handler(async () => {
    // Bu kod SADECE sunucuda calisir
    return db.post.findMany({ orderBy: { createdAt: 'desc' } })
  })

// Istemciden cagirma
const posts = await getPosts()   // tip: Post[]

import { z } from 'zod'

const yeniYazi = z.object({
  baslik: z.string().min(3),
  icerik: z.string().min(10),
})

export const addPost = createServerFn({ method: 'POST' })
  .validator((veri: unknown) => yeniYazi.parse(veri))
  .handler(async ({ data }) => {
    return db.post.create({ data })
  })

import { createMiddleware } from '@tanstack/react-start'

const authMiddleware = createMiddleware()
  .server(async ({ next, context }) => {
    const user = await getUserFromSession()
    if (!user) throw new Error('Yetkisiz erisim')
    return next({ context: { user } })
  })

export const deletePost = createServerFn({ method: 'POST' })
  .middleware([authMiddleware])
  .validator((d: unknown) => z.object({ id: z.string() }).parse(d))
  .handler(async ({ data, context }) => {
    if (context.user.role !== 'admin') throw new Error('Yetki yok')
    return db.post.delete({ where: { id: data.id } })
  })

Veri Yükleme ve Streaming (Data Loading and Streaming)

TanStack Start, TanStack Query ile doğal biçimde çalışır. Rota loader'ında ön yükleme yapıp bileşen içinde Query ile devam edebilirsiniz:

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(
      postQueryOptions(params.postId)
    ),
  component: PostPage,
})

function PostPage() {
  const { postId } = Route.useParams()
  const { data: post } = useSuspenseQuery(postQueryOptions(postId))
  return <h1>{post.title}</h1>
}

Bu kalıbın güzelliği şu: sayfa sunucuda render edilirken veri hazır olur (SEO ve ilk yükleme için iyi), istemci tarafında ise Query'nin önbellek, yeniden doğrulama ve arka plan yenileme yetenekleri devreye girer.

Performans

Topluluk tarafından yayınlanan bir kıyaslamada, veri yoğun bir uygulamanın TanStack Start'a taşınmasıyla saniyedeki istek sayısında yaklaşık 5,5 kat, ortalama gecikmede yaklaşık 10 kat iyileşme raporlandı. Bu rakamları mutlak gerçek olarak almayın — kıyaslamalar test senaryosuna çok bağlıdır. Ancak yönü doğru: RSC yükü olmayan, istemci öncelikli bir mimari sunucu tarafında daha az iş yapar.

TanStack Start vs Next.js: Dürüst Karşılaştırma

Buradan çıkarılacak sonuç "biri diğerinden iyi" değil. İki framework farklı problemleri çözüyor. Next.js içerik ve pazarlama sitelerinde, görsel optimizasyonu ve artımlı statik üretim gibi olgun araçlarıyla önde. TanStack Start ise veri yoğun, oturum açmalı, karmaşık filtreleme ve durum yönetimi olan uygulamalarda parlıyor.

Hangi Projede Hangisi? (When to Choose What)

* Yonetim paneli / dashboard / ic arac yaziyorsaniz
* Karmasik filtre ve URL durumu yonetiyorsaniz
* TanStack Query'yi zaten yogun kullaniyorsaniz
* Tip guvenligini pazarlik konusu yapmiyorsaniz
* RSC'nin zihinsel yukunu istemiyorsaniz
* Farkli platformlara dagitim esnekligi ariyorsaniz

* Icerik/blog/e-ticaret sitesi yapiyorsaniz
* SEO ve statik uretim on planda ise
* Genis eklenti ekosistemine ihtiyaciniz varsa
* Ekibiniz zaten Next.js biliyorsa
* React Server Components'i bugun kullanmak istiyorsaniz
* Ise alim havuzunun genisligi onemliyse

Alesta Web olarak pratikte uyguladığımız ayrım şu: müşteriye bakan içerik siteleri bir tarafta, işletme içi veri uygulamaları diğer tarafta. Aynı şirket için ikisini farklı çerçevelerle yapmak hiç de tuhaf değil.

Eksikler ve Dikkat Edilecekler (Limitations)

• React Server Components deneysel. RSC üzerine kurulu bir mimari planlıyorsanız bekleyin.
• Ekosistem genç. Hazır çözüm ve üçüncü taraf entegrasyon sayısı Next.js'in çok gerisinde. Kimlik doğrulama, ödeme, CMS entegrasyonlarını büyük ihtimalle elle kuracaksınız.
• Örnek ve eğitim içeriği sınırlı. Bir sorunla karşılaştığınızda arama sonuçları Next.js kadar zengin değil.
• Görsel optimizasyonu yerleşik değil. Next.js'in next/image karşılığı için harici çözüm gerekir.
• Dokümantasyon tutarsızlıkları. v1 geçişi sırasında bazı sayfalar güncellenmemiş durumda; kaynak koda bakmanız gerekebilir.

📚 Kaynaklar ve Referanslar / Sources and References

Bu rehberdeki bilgiler resmî dokümantasyon ve topluluk kaynaklarından derlenmiş, örnek kodlar Alesta Web ekibi tarafından yapılandırılmıştır:

• TanStack Start — Resmî Dokümantasyon · Genel bakış ve API referansı
• TanStack Router Docs · Yönlendirme ve tip güvenliği detayları
• Nitro · Sunucu katmanı ve dağıtım hedefleri
• TanStack Query · Veri yükleme ve önbellek entegrasyonu
• Vite · Derleme ve geliştirme sunucusu