2nd/10_Wiki/Topics/Frontend/단일 페이지 애플리케이션 (SPA).md

---
id: wiki-2026-0508-단일-페이지-애플리케이션-spa
title: 단일 페이지 애플리케이션 (SPA)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [SPA, Single Page Application, 클라이언트 사이드 라우팅]
duplicate_of: none
source_trust_level: A
confidence_score: 0.93
verification_status: applied
tags: [frontend, architecture, spa, routing, react]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: React 19 / Vite 6
---

# 단일 페이지 애플리케이션 (SPA)

## 매 한 줄
> **"매 single HTML shell 의 매 load 후 매 client-side 의 매 view transition 의 매 처리"**. 매 2010s 의 AngularJS / Backbone 의 매 시작, 매 React / Vue 의 매 mainstream 화, 매 2026 의 SPA 는 매 React 19 / 매 TanStack Router / 매 Vite 6 의 매 stack 의 매 표준. 매 SSR / 매 RSC hybrid 의 매 부상에도 매 dashboard / 매 internal tool / 매 high-interactivity app 의 매 SPA 의 매 적합.

## 매 핵심

### 매 동작 모델
- 매 initial request: 매 single `index.html` + 매 JS bundle.
- 매 client router: 매 `history.pushState` 의 매 URL 변경, 매 component 의 매 swap.
- 매 data: 매 fetch / 매 GraphQL / 매 RPC 의 매 client 직접 호출.

### 매 장점 / 매 단점
- 장점: 매 빠른 navigation (no full reload), 매 rich interaction, 매 offline 가능.
- 단점: 매 initial load 무거움, 매 SEO 취약 (매 SSR / 매 prerender 의 보완 필요), 매 JS 의존.

### 매 응용
1. Admin dashboard.
2. SaaS internal tool (Linear, Figma).
3. Realtime collaborative app.

## 💻 패턴

### Vite 6 + React 19 SPA shell
```tsx
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider } from "@tanstack/react-router";
import { router } from "./router";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>,
);
```

### TanStack Router file-based routing
```tsx
// routes/__root.tsx
import { Outlet, createRootRoute } from "@tanstack/react-router";
export const Route = createRootRoute({ component: () => <Outlet /> });

// routes/users/$id.tsx
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/users/$id")({
  loader: ({ params }) => fetch(`/api/users/${params.id}`).then(r => r.json()),
  component: UserDetail,
});

function UserDetail() {
  const user = Route.useLoaderData();
  return <h1>{user.name}</h1>;
}
```

### Code splitting per route
```tsx
import { lazy } from "react";
const Settings = lazy(() => import("./pages/Settings"));
// Vite 자동 chunk 분리 + prefetch
```

### Data fetching (TanStack Query)
```tsx
import { useQuery } from "@tanstack/react-query";

function Users() {
  const { data, isLoading } = useQuery({
    queryKey: ["users"],
    queryFn: () => fetch("/api/users").then(r => r.json()),
    staleTime: 60_000,
  });
  if (isLoading) return <Spinner />;
  return <UserList users={data} />;
}
```

### Client-side auth guard
```tsx
import { redirect } from "@tanstack/react-router";

export const Route = createFileRoute("/_authed")({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: "/login" });
    }
  },
});
```

### Prerender for SEO (vite-plugin-ssr or similar)
```ts
// vite.config.ts
import { defineConfig } from "vite";
import ssr from "vite-plugin-ssr/plugin";

export default defineConfig({
  plugins: [ssr({ prerender: true })],
});
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Public marketing | SSR / SSG (Next.js, Astro) — SPA 부적합 |
| Admin / dashboard | SPA 적합 |
| E-commerce | SSR + island hydration (hybrid) |
| Realtime collab | SPA + WebSocket |

**기본값**: 매 internal high-interactivity tool 은 매 SPA, 매 public 페이지는 매 SSR / 매 hybrid.

## 🔗 Graph
- 부모: [[Large_Frontend_Projects|Frontend Architecture]]
- 변형: [[SSR]] · [[SSG]] · [[Islands Architecture]] · [[React Server Components]]
- 응용: [[단일 페이지 애플리케이션(SPA) 렌더링 설계]] · [[단일 페이지 애플리케이션(SPA) 아키텍처 설계]]
- Adjacent: [[Code Splitting]] · [[Client-Side Routing]] · [[State Management]]

## 🤖 LLM 활용
**언제**: 매 highly interactive / 매 authenticated dashboard / 매 internal tool 의 매 설계 의 권장.
**언제 X**: 매 SEO 핵심 페이지 / 매 first-paint 매 critical / 매 low-end device target — 매 SSR 또는 매 hybrid 의 권장.

## ❌ 안티패턴
- **Public 마케팅 SPA**: SEO / 매 first paint 의 매 부담.
- **하나의 거대 bundle**: 매 code splitting 의 X — 매 initial load 의 매 폭증.
- **Client-only auth**: 매 sensitive route 의 매 server-side guard 의 매 부재.

## 🧪 검증 / 중복
- Verified (React 19 / Vite 6 / TanStack Router v1 docs, MDN — History API).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Vite 6 / React 19 / TanStack Router 의 modern SPA stack 정리 |