RSC 없이 DB 직접 호출부터 스트리밍까지 — TanStack Start와 Next.js, 풀스택 경계가 어디서 갈리는가

// app/routes/dashboard.tsx
export const Route = createFileRoute('/dashboard')({
  // 완전한 서버 렌더링 — SEO가 중요한 페이지에 적합합니다
  ssr: true,
 
  // 서버에서 데이터만, 컴포넌트 렌더는 클라이언트
  // ssr: 'data-only',
 
  // 순수 클라이언트 SPA — 어드민 내부 페이지 등
  // ssr: false,
 
  loader: async () => fetchDashboardData(),
  component: DashboardPage,
})

// app/functions/user.ts
// 이 파일의 코드는 서버에서만 실행됩니다
import { createServerFn } from '@tanstack/start'
import { z } from 'zod'
import { db } from '~/server/db'  // Prisma 또는 Drizzle 모두 동일한 방식으로 씁니다
 
const getUser = createServerFn({ method: 'GET' })
  .validator(z.object({ id: z.string() }))
  .handler(async ({ data }) => {
    return db.user.findUnique({ where: { id: data.id } })
  })
 
const updateUserProfile = createServerFn({ method: 'POST' })
  .validator(z.object({
    id: z.string(),
    name: z.string().min(1),
    email: z.string().email(),
  }))
  .handler(async ({ data }) => {
    return db.user.update({
      where: { id: data.id },
      data: { name: data.name, email: data.email },
    })
  })
 
export { getUser, updateUserProfile }

// app/routes/profile.$userId.tsx
import { useState } from 'react'
import { createFileRoute } from '@tanstack/react-router'
import { getUser, updateUserProfile } from '~/functions/user'
 
export const Route = createFileRoute('/profile/$userId')({
  loader: async ({ params }) => {
    // 로더에서 서버 함수 호출 — SSR 시 서버 사이드에서 직접 실행됩니다
    return getUser({ data: { id: params.userId } })
  },
  component: ProfilePage,
})
 
function ProfilePage() {
  const user = Route.useLoaderData()
  const [error, setError] = useState<string | null>(null)
 
  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    try {
      await updateUserProfile({
        data: {
          id: user.id,
          name: formData.get('name') as string,
          email: formData.get('email') as string,
        },
      })
    } catch (err) {
      // createServerFn에서 throw한 Error가 그대로 클라이언트에 전달됩니다
      setError(err instanceof Error ? err.message : '오류가 발생했습니다')
    }
  }
 
  return (
    <form onSubmit={handleSubmit}>
      {error && <p className="error-message">{error}</p>}
      <input name="name" defaultValue={user.name} />
      <input name="email" defaultValue={user.email} />
      <button type="submit">저장</button>
    </form>
  )
}

// app/functions/analytics.ts
import { createServerFn } from '@tanstack/start'
import { z } from 'zod'
import { db } from '~/server/db'
 
export const getRevenueData = createServerFn({ method: 'GET' })
  .handler(async () => {
    // 무거운 DB 집계 쿼리도 서버에서만 실행됩니다
    return db.order.groupBy({
      by: ['createdAt'],
      _sum: { amount: true },
      orderBy: { createdAt: 'asc' },
    })
  })
 
export const getUserActivity = createServerFn({ method: 'GET' })
  .validator(z.object({ days: z.number().default(30) }))
  .handler(async ({ data }) => {
    const since = new Date(Date.now() - data.days * 86400 * 1000)
    return db.userEvent.findMany({
      where: { createdAt: { gte: since } },
    })
  })

// app/routes/analytics.tsx
import { Suspense } from 'react'
import { useSuspenseQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'
import { getRevenueData, getUserActivity } from '~/functions/analytics'
 
export const Route = createFileRoute('/analytics')({
  ssr: true,
  component: AnalyticsPage,
})
 
function RevenueChart() {
  // useSuspenseQuery — 이 컴포넌트가 Suspense 경계 안에 있어야 동작합니다
  const { data } = useSuspenseQuery({
    queryKey: ['revenue'],
    queryFn: () => getRevenueData(),
  })
  return <LineChart data={data} />
}
 
function UserActivityTable() {
  const { data } = useSuspenseQuery({
    queryKey: ['user-activity'],
    queryFn: () => getUserActivity({ data: { days: 30 } }),
  })
  return <DataTable rows={data} />
}
 
function AnalyticsPage() {
  return (
    <div className="grid gap-6">
      {/* 즉시 렌더되는 레이아웃 */}
      <PageHeader title="Analytics" />
 
      {/* 각 Suspense 경계가 독립적으로 스트리밍됩니다 */}
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>
 
      <Suspense fallback={<TableSkeleton />}>
        <UserActivityTable />
      </Suspense>
    </div>
  )
}

// app/routes/admin/orders.tsx
import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/start'
import { z } from 'zod'
import { db } from '~/server/db'
import { requireAdmin } from '~/server/auth'
 
// 서버 함수 — DB 접근, 권한 체크 전부 서버에서 처리됩니다
const getOrders = createServerFn({ method: 'GET' })
  .validator(z.object({
    page: z.number().default(1),
    status: z.enum(['pending', 'shipped', 'delivered']).optional(),
  }))
  .handler(async ({ data }) => {
    // 인증 체크는 클라이언트에 로직이 노출되지 않습니다
    await requireAdmin()
 
    return db.order.findMany({
      where: { status: data.status },
      skip: (data.page - 1) * 20,
      take: 20,
      include: { user: true, items: true },
    })
  })
 
export const Route = createFileRoute('/admin/orders')({
  // 로더는 서버에서, 렌더는 클라이언트에서
  ssr: 'data-only',
 
  // URL 검색 파라미터를 타입 안전하게 검증합니다 (TanStack Router 고유 기능)
  validateSearch: z.object({
    page: z.number().catch(1),
    status: z.enum(['pending', 'shipped', 'delivered']).optional(),
  }),
 
  loader: async ({ location }) => {
    // location.search는 validateSearch 스키마로 이미 타입이 추론됩니다
    const { page, status } = location.search
    return getOrders({ data: { page, status } })
  },
 
  component: OrdersPage,
})
 
function OrdersPage() {
  const orders = Route.useLoaderData()
  const { page, status } = Route.useSearch()
 
  return (
    <div>
      <OrderFilters currentStatus={status} />
      <OrderTable orders={orders} />
      <Pagination currentPage={page} />
    </div>
  )
}

// app/routes/analytics.tsx
import { Suspense } from 'react'
import { useSuspenseQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'
import { getRevenueData, getUserActivity } from '~/functions/analytics'
 
export const Route = createFileRoute('/analytics')({
  ssr: true,
  component: AnalyticsPage,
})
 
function RevenueChart() {
  const { data } = useSuspenseQuery({
    queryKey: ['revenue'],
    queryFn: () => getRevenueData(),
  })
  return <LineChart data={data} />
}
 
function UserActivityTable() {
  const { data } = useSuspenseQuery({
    queryKey: ['user-activity'],
    queryFn: () => getUserActivity({ data: { days: 30 } }),
  })
  return <DataTable rows={data} />
}
 
function AnalyticsPage() {
  return (
    <div className="grid gap-6">
      <PageHeader title="Analytics" />
 
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>
 
      <Suspense fallback={<TableSkeleton />}>
        <UserActivityTable />
      </Suspense>
    </div>
  )
}

// 기존 React Router v6
// routes/dashboard.tsx
import { useLoaderData } from 'react-router-dom'
 
export async function loader() {
  return fetch('/api/dashboard').then(r => r.json())
}
 
export default function Dashboard() {
  const data = useLoaderData()
  return <DashboardUI data={data} />
}

// TanStack Start로 전환
// app/routes/dashboard.tsx
import { createFileRoute } from '@tanstack/react-router'
import { getDashboardData } from '~/functions/dashboard'
 
export const Route = createFileRoute('/dashboard')({
  ssr: 'data-only',
  loader: async () => getDashboardData(),
  component: Dashboard,
})
 
function Dashboard() {
  // useLoaderData 대신 Route.useLoaderData — 리턴 타입이 자동 추론됩니다
  const data = Route.useLoaderData()
  return <DashboardUI data={data} />
}