> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSR 설정

> Sonamu의 TanStack Router + Vite SSR 구성

export const FileItem = ({name, description, children}) => {
  const isLeaf = !children;
  const ext = getFileExtension(name);
  const extStyle = ext ? getExtensionStyle(ext) : null;
  return <div style={{
    marginLeft: "30px"
  }}>
      <div style={{
    display: "flex",
    alignItems: "center",
    gap: "4px"
  }}>
        <span style={{
    position: "relative",
    display: "inline-block"
  }}>
          <span className="file-icon">{isLeaf && !name.endsWith("/") ? "📄" : "📁"}</span>
          {ext && <span style={{
    position: "absolute",
    bottom: "2px",
    right: "0px",
    fontSize: "5px",
    fontWeight: "bold",
    padding: "1px",
    borderRadius: "2px",
    lineHeight: "1",
    minWidth: "8px",
    textAlign: "center",
    ...extStyle
  }}>
              {ext}
            </span>}
        </span>
        <code>{name}</code>
        {description && <span className="description"> - {description}</span>}
      </div>
      {children}
    </div>;
};

export const FileTree = ({children}) => {
  return <div className="file-tree" style={{
    margin: "20px",
    marginLeft: "-30px"
  }}>
      {children}
    </div>;
};

Sonamu에서 Server-Side Rendering(SSR)을 설정하고 사용하는 방법을 알아봅니다.

## SSR 개요

<CardGroup cols={2}>
  <Card title="TanStack Router" icon="route">
    파일 기반 라우팅 Type-safe 네비게이션
  </Card>

  <Card title="Vite SSR" icon="bolt">
    빠른 빌드 HMR 지원
  </Card>

  <Card title="Direct API Call" icon="server">
    HTTP 오버헤드 없음 빠른 응답
  </Card>

  <Card title="TanStack Query" icon="arrows-rotate">
    Hydration 자동화 캐싱 통합
  </Card>
</CardGroup>

## Sonamu SSR 아키텍처

Sonamu는 **TanStack Router + Vite**를 사용하여 SSR을 구현합니다.

### 핵심 구성 요소

<FileTree>
  <FileItem name="web/src/">
    <FileItem name="entry-server.generated.tsx" description="서버 렌더링 엔트리 (자동 생성)" />

    <FileItem name="entry-client.tsx" description="클라이언트 하이드레이션 엔트리" />

    <FileItem name="routeTree.gen.ts" description="TanStack Router 라우트 트리 (자동 생성)" />

    <FileItem name="routes/" description="파일 기반 라우트">
      <FileItem name="__root.tsx" description="루트 레이아웃" />

      <FileItem name="index.tsx" description="/ 경로" />

      <FileItem name="users/">
        <FileItem name="$id.tsx" description="/users/:id 경로" />
      </FileItem>
    </FileItem>
  </FileItem>
</FileTree>

### entry-server.generated.tsx

서버에서 React를 렌더링하는 진입점입니다 (자동 생성됨):

```typescript theme={null}
// web/src/entry-server.generated.tsx
import { QueryClient, dehydrate } from "@tanstack/react-query";
import { createMemoryHistory, createRouter, RouterProvider } from "@tanstack/react-router";
import { Suspense } from "react";
import { renderToString } from "react-dom/server";
import { routeTree } from "./routeTree.gen";

export type PreloadedData = {
  queryKey: any[];
  data: any;
};

export async function render(url: string, preloadedData: PreloadedData[] = []) {
  // QueryClient 생성
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5000,
        retry: false,
      },
    },
  });

  // Preloaded 데이터를 queryClient에 직접 주입
  for (const { queryKey, data } of preloadedData) {
    queryClient.setQueryData(queryKey, data);
  }

  // Dehydrate
  const dehydratedState = dehydrate(queryClient);

  // SSR용 메모리 히스토리 생성
  const memoryHistory = createMemoryHistory({
    initialEntries: [url],
  });

  // Router 생성 (SSR 모드)
  const router = createRouter({
    routeTree,
    context: { queryClient },
    history: memoryHistory,
    defaultPreload: "intent",
  });

  // 라우터 초기화: SSR에서 반드시 await router.load() 호출 필요
  await router.load();

  // RouterProvider만 렌더링 (Suspense로 래핑 - hydration mismatch 방지)
  const appHtml = renderToString(
    <Suspense fallback={null}>
      <RouterProvider router={router} />
    </Suspense>,
  );

  return {
    html: appHtml,
    dehydratedState,
  };
}
```

### entry-client.tsx

클라이언트에서 React를 하이드레이션하는 진입점입니다:

```typescript theme={null}
// web/src/entry-client.tsx
import { hydrate, QueryClient } from "@tanstack/react-query";
import { createRouter, RouterProvider } from "@tanstack/react-router";
import ReactDOM from "react-dom/client";
import { routeTree } from "./routeTree.gen";
import { dateReviver } from "./services/sonamu.shared";

// SSR 데이터 타입
declare global {
  interface Window {
    __SONAMU_SSR__?: any;
    __SONAMU_SSR_CONFIG__?: {
      disableHydrate?: boolean;
    };
  }
}

// QueryClient 생성
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5000,
      retry: false,
      refetchOnMount: true,
    },
  },
});

// SSR 데이터 복원
const dehydratedState = window.__SONAMU_SSR__
  ? JSON.parse(JSON.stringify(window.__SONAMU_SSR__), dateReviver)
  : undefined;

if (dehydratedState) {
  hydrate(queryClient, dehydratedState);
}

// Router 생성
const router = createRouter({
  routeTree,
  context: { queryClient },
  defaultPreload: "intent",
});

await router.load();

// Hydration
if (document.documentElement.innerHTML && dehydratedState) {
  // SSR 페이지 - Hydration
  ReactDOM.hydrateRoot(document, <RouterProvider router={router} />);
} else {
  // Pure CSR 페이지 - 새로 렌더링
  ReactDOM.createRoot(document).render(<RouterProvider router={router} />);
}
```

## TanStack Router 라우트 구조

### Root Route

```typescript theme={null}
// web/src/routes/__root.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";

export interface RouterContext {
  queryClient: QueryClient;
}

export const Route = createRootRouteWithContext<RouterContext>()({
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1.0" },
      { title: "My App" },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  const { queryClient } = Route.useRouteContext();

  return (
    <html lang="ko">
      <head>
        <HeadContent />
      </head>
      <body>
        <div id="root">
          <QueryClientProvider client={queryClient}>
            <Outlet />
          </QueryClientProvider>
        </div>
        <Scripts />
      </body>
    </html>
  );
}
```

### 파일 라우트

```typescript theme={null}
// web/src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: HomePage,
});

function HomePage() {
  return (
    <div>
      <h1>Home Page</h1>
    </div>
  );
}
```

### 동적 라우트

```typescript theme={null}
// web/src/routes/users/$id.tsx
import { createFileRoute } from "@tanstack/react-router";
import { UserService } from "@/services/services.generated";

export const Route = createFileRoute("/users/$id")({
  component: UserPage,
});

function UserPage() {
  const { id } = Route.useParams();
  const { data } = UserService.useUser("C", parseInt(id));

  return (
    <div>
      <h1>{data?.user.username}</h1>
      <p>{data?.user.email}</p>
    </div>
  );
}
```

## Vite 설정

```typescript theme={null}
// web/vite.config.ts
import { tanstackRouter } from "@tanstack/router-plugin/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig(({ isSsrBuild }) => ({
  plugins: [
    react(),
    tanstackRouter({
      autoCodeSplitting: true,
      generatedRouteTree: "./src/routeTree.gen.ts",
    }),
  ],
  build: {
    outDir: "dist/client",
    rollupOptions: {
      output: isSsrBuild
        ? {}
        : {
            manualChunks: {
              "vendor-react": ["react", "react-dom"],
              "vendor-tanstack": ["@tanstack/react-query", "@tanstack/react-router"],
            },
          },
    },
  },
  ssr: {
    noExternal: true, // Production 빌드 시 모든 의존성 번들에 포함
  },
}));
```

## SSR vs CSR

Sonamu는 **하이브리드 접근 방식**을 사용합니다:

### SSR 렌더링 (데이터 프리로딩 시)

```typescript theme={null}
// registerSSR로 등록된 경로
// → 서버에서 HTML 생성 + 데이터 포함
// → 클라이언트에서 hydration
```

**장점**:

* 빠른 First Contentful Paint
* SEO 최적화
* 초기 데이터 즉시 표시

### CSR 렌더링 (기본)

```typescript theme={null}
// registerSSR 없는 경로
// → 클라이언트에서 직접 렌더링
// → API 호출하여 데이터 로드
```

**장점**:

* 서버 부하 감소
* 간단한 구현
* 빠른 개발

## 개발 vs 프로덕션

### 개발 모드

```bash theme={null}
sonamu dev            # 통합 모드 (= sonamu dev all)
sonamu dev all        # 통합 모드 (one-port: API + Web)
sonamu dev api        # API-only 모드 (Vite 통합 비활성)
sonamu dev web        # Vite 단독 실행
sonamu dev web -- --port 5173 --host 0.0.0.0  # Vite 옵션 전달
```

* `dev all`: API 서버가 Vite를 통합하여 하나의 포트로 API + Web 서빙 (HMR 지원)
* `dev api`: API만 실행. Web이 필요 없거나 Vite를 별도로 실행하고 싶을 때 사용
* `dev web`: Vite 개발 서버만 단독 실행. `--` 뒤에 Vite 옵션 전달 가능

### 프로덕션 빌드

```bash theme={null}
sonamu build          # 전체 빌드 (= sonamu build all)
sonamu build api      # API만 빌드
sonamu build web      # Web만 빌드
```

**빌드 결과**:

```
web/dist/                               # Web 빌드 원본
├── client/                             # 클라이언트 번들
└── server/                             # SSR 번들

api/web-dist/                           # Web 빌드 미러 (배포용)
├── client/                             # = web/dist/client 미러
│   ├── index.html
│   └── assets/
└── server/                             # = web/dist/server 미러
    └── entry-server.generated.js

api/dist/                               # API 빌드 결과
└── ssr/
    └── routes.js                       # SSR 라우트 (API 소유)
```

## 주의사항

<Warning>
  **Sonamu SSR 사용 시 주의사항**: 1. **TanStack Router 기반**: Next.js App Router가 아닙니다 2.
  **entry-server.generated.tsx는 자동 생성**: 직접 수정하지 마세요 3. **window 객체 주의**:
  서버에서는 window가 없습니다 4. **dateReviver 필수**: Date 객체 직렬화/역직렬화 처리 5.
  **registerSSR 사용**: 데이터 프리로딩은 다음 문서 참고
</Warning>

## 다음 단계

<CardGroup cols={2}>
  <Card title="데이터 프리로딩" icon="bolt" href="/ko/frontend-integration/ssr/preloading-data">
    registerSSR 사용법
  </Card>

  <Card title="Hydration 전략" icon="droplet" href="/ko/frontend-integration/ssr/hydration-strategies">
    하이드레이션 최적화
  </Card>

  <Card title="캐시 제어" icon="database" href="/ko/frontend-integration/ssr/cache-control">
    TanStack Query 캐싱
  </Card>

  <Card title="TanStack Router 공식 문서" icon="external-link" href="https://tanstack.com/router">
    라우터 상세 가이드
  </Card>
</CardGroup>