[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,131 +2,227 @@
|
||||
id: wiki-2026-0508-server-side-rendering-ssr
|
||||
title: Server Side Rendering (SSR)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-REINFORCE-AUTO-8F532C]
|
||||
aliases: [SSR, Server Rendering, isomorphic rendering]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
tags: [auto-reinforced]
|
||||
verification_status: applied
|
||||
tags: [ssr, react, nextjs, rendering, performance]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-03
|
||||
github_commit: "[P-Reinforce] Continuous Worker - Server Side Rendering (SSR)"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: TypeScript
|
||||
framework: Next.js 15 / React 19
|
||||
---
|
||||
|
||||
# [[Server Side Rendering (SSR)|Server Side Rendering (SSR)]]
|
||||
# Server Side Rendering (SSR)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
서버 사이드 렌더링(SSR)은 클라이언트(브라우저)에서 자바스크립트를 다운로드하여 빈 화면을 채우는 대신, 서버 환경에서 애플리케이션의 초기 렌더링을 수행하여 완성된 HTML을 생성하고 전송하는 렌더링 전략입니다 [1-3]. 이는 사용자가 자바스크립트 번들이 로드될 때까지 빈 화면을 기다려야 하는 성능 문제를 해결하기 위해 도입되었습니다 [1, 4]. 클라이언트는 이 HTML을 전달받은 후, 이벤트 핸들러를 연결하여 애플리케이션을 상호작용 가능하게 만드는 '하이드레이션(Hydration)' 과정을 거칩니다 [5, 6].
|
||||
## 매 한 줄
|
||||
> **"매 SSR 은 server 에서 HTML 을 생성해 first paint 를 빠르게, SEO 를 가능하게"**. 2026 기준 React 19 의 streaming SSR + Suspense + Server Components 가 표준. 매 trade-off 는 server compute cost vs CSR-only 의 blank-screen 제거. 매 modern 변형: SSG (build-time), ISR (revalidate), PPR (Partial Prerender).
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **SSR의 동작 방식 및 등장 배경:** 기존 클라이언트 사이드 렌더링(CSR) 방식은 사용자의 기기에 대용량의 자바스크립트가 다운로드되고 실행될 때까지 빈 하얀 화면만 노출되는 성능 병목 현상이 있었습니다 [1, 7]. 이를 개선하기 위해 Next.js, Remix, Vue 등의 메타 프레임워크는 서버에서 초기 HTML을 미리 렌더링(Pre-render)하여 클라이언트에 제공하는 SSR 아키텍처를 도입했습니다 [1, 2, 8].
|
||||
* **하이드레이션(Hydration) 메커니즘:** 서버가 렌더링한 HTML은 화면에 즉시 콘텐츠를 보여주지만, 초기에는 상호작용이 불가능한 상태입니다 [9]. 브라우저가 자바스크립트를 다운로드한 후 React나 Vue 같은 프레임워크가 기존 DOM 트리를 순회하며 이벤트 핸들러를 부착하고 상호작용을 활성화하는데, 이 과정을 마른 HTML에 생명력을 불어넣는다는 의미에서 '하이드레이션'이라고 부릅니다 [5, 6, 10].
|
||||
* **React Server Components (RSC)와의 시너지:** SSR은 RSC(React Server Components)를 대체하는 것이 아니라 완벽하게 상호 보완하는 렌더링 기술입니다 [11, 12]. SSR은 초기 HTML을 생성하는 데 사용되며, RSC는 컴포넌트를 클라이언트 자바스크립트 번들에 포함시키지 않고 서버에서만 실행한 뒤 'RSC 페이로드'로 직렬화합니다 [3, 11, 13]. 두 기술을 결합하면 하이드레이션 단계가 생략되는 서버 컴포넌트의 이점과 초기 화면 로딩 속도를 높이는 SSR의 이점을 동시에 누릴 수 있습니다 [12, 14].
|
||||
* **Vue 3.5의 최적화 패턴:** 대규모 애플리케이션을 지원하기 위해 Vue 3.5는 뷰포트(Viewport) 내에 컴포넌트가 보일 때만 하이드레이션을 활성화하는 '지연 하이드레이션(Lazy Hydration)' 기능을 도입하여 초기 로드 시간을 획기적으로 줄였습니다 [15, 16]. 또한 `useId()` API를 도입해 서버와 클라이언트 렌더링 간에 일관된 고유 ID를 보장함으로써 하이드레이션 불일치(Mismatch) 현상을 방지합니다 [15, 17].
|
||||
## 매 핵심
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
* **하이드레이션 갭(Hydration Gap)과 'Two-Trip' 한계:** SSR은 초기 화면은 빠르게 보여주지만, 자바스크립트가 로드되어 하이드레이션이 끝날 때까지 사용자가 버튼을 눌러도 반응하지 않는 '하이드레이션 갭'이 발생합니다 [9, 10]. 또한 서버에서 렌더링을 마쳤음에도 불구하고, 클라이언트가 다시 자바스크립트를 다운로드하고 실행해야 하는 중복 작업(Two-Trip)이 여전히 남는다는 한계가 있습니다 [4].
|
||||
* **트리 블로킹(Tree Blocking):** 하이드레이션은 DOM 트리를 순차적으로 처리하므로, 트리 상단에 무겁고 느린 컴포넌트가 존재할 경우 트리 하단의 상호작용까지 지연되는 문제가 발생합니다 [10]. 이는 React 18의 사용자 상호작용을 먼저 처리하는 선택적 하이드레이션(Selective Hydration) 메커니즘을 통해 완화해야 합니다 [18].
|
||||
* **서버 환경에서의 상태 오염(State Pollution):** Vue 등에서 서버 사이드 렌더링을 구현할 때, 전역 스토어를 싱글톤(Singleton)으로 사용하면 여러 요청 간에 상태가 공유되어 데이터 유출 문제가 발생할 수 있습니다 [19, 20]. 따라서 요청마다 별도의 스토어(예: Pinia) 인스턴스가 생성되도록 엄격하게 아키텍처를 설계해야 합니다 [20].
|
||||
* **입력 유효성 검사 누락에 따른 보안 취약점:** SSR 환경에서 서버 액션을 내부 로컬 함수처럼 생각하여 입력값 검증을 생략할 경우, 누구나 요청을 보낼 수 있는 공용 HTTP 엔드포인트의 특성상 원격 코드 실행(RCE) 등의 치명적인 취약점(예: React2Shell)에 노출될 수 있습니다 [21, 22].
|
||||
### 매 rendering modes
|
||||
- **CSR**: 매 client only — slow first paint, no SEO without JS
|
||||
- **SSR**: 매 server-render full HTML per request
|
||||
- **SSG**: 매 build-time HTML (static)
|
||||
- **ISR**: 매 SSG + on-demand or time-based revalidation
|
||||
- **PPR**: 매 partial prerender — static shell + dynamic holes (Next.js 15)
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
### Related Concepts
|
||||
### 매 hydration
|
||||
- Server HTML 송신 → client JS 가 attach (event handler 연결)
|
||||
- Streaming SSR: HTML 을 chunk 로 진행 송신
|
||||
- Selective hydration: visible / interacted 부분 우선
|
||||
|
||||
#### [렌더링 전략 및 메커니즘]
|
||||
- [[Hydration]]
|
||||
- 연결 이유: SSR을 통해 서버에서 생성된 정적 HTML을 클라이언트 측에서 상호작용 가능한 동적 상태로 만드는 필수적인 연결 고리이기 때문입니다 [5, 6].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 초기 페이지 로딩 시 화면은 보이지만 상호작용이 불가능한 현상인 '하이드레이션 갭(Hydration Gap)'의 발생 원리와, 이를 최적화하기 위한 프레임워크의 내부 메커니즘을 이해할 수 있습니다 [9, 10].
|
||||
- [[React Server Components]]
|
||||
- 연결 이유: SSR의 Two-Trip 문제를 해결하고 하이드레이션을 생략하기 위해, 클라이언트 자바스크립트 번들에 포함되지 않고 서버에서만 렌더링되도록 설계된 React의 최신 아키텍처 패턴이기 때문입니다 [11, 13, 14].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: SSR이 초기 HTML을 렌더링하는 방식과 RSC가 페이로드를 스트리밍하는 방식이 어떻게 결합되어 클라이언트 성능을 최적화하는지 명확히 구분하고 응용할 수 있습니다 [11, 12].
|
||||
### 매 응용
|
||||
1. Marketing / blog (SEO + fast paint).
|
||||
2. E-commerce PDP (per-user pricing + SEO).
|
||||
3. Dashboard shells (PPR — static shell + dynamic data).
|
||||
|
||||
#### [상태 관리 및 최적화 도구]
|
||||
- [[Pinia]]
|
||||
- 연결 이유: Vue 기반의 대규모 애플리케이션에서 SSR 적용 시, 상태 오염(State Pollution)과 메모리 누수를 방지하기 위한 핵심 상태 관리 라이브러리이기 때문입니다 [19, 20].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: SSR 서버 환경에서 여러 사용자의 요청을 처리할 때 독립적인 스토어 인스턴스를 유지해야 하는 서버 측 렌더링의 제약 사항과 상태 관리 패턴을 파악할 수 있습니다 [20].
|
||||
- [[Lazy Hydration]]
|
||||
- 연결 이유: Vue 3.5 등 최신 프레임워크에서 SSR의 초기 하이드레이션 비용을 줄이기 위해, 컴포넌트가 뷰포트(Viewport)에 노출될 때까지 하이드레이션을 지연시키는 핵심 최적화 패턴입니다 [15].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 동기적이고 순차적인 기존 하이드레이션의 병목을 극복하고, 대규모 애플리케이션의 초기 렌더링 퍼포먼스를 극대화하는 실전 테크닉을 이해할 수 있습니다 [15].
|
||||
## 💻 패턴
|
||||
|
||||
### Deeper Research Questions
|
||||
### Next.js 15 RSC + streaming
|
||||
```tsx
|
||||
// app/page.tsx
|
||||
import { Suspense } from "react";
|
||||
import { ProductGrid } from "./product-grid";
|
||||
|
||||
- 단일 페이지 애플리케이션(SPA)의 CSR 방식과 SSR 방식을 결합할 때, 브라우저의 TTI(Time to Interactive)와 FCP(First Contentful Paint)는 각각 어떻게 변화하며 최적의 트레이드오프 지점은 어디인가?
|
||||
- Vue의 지연 하이드레이션(Lazy Hydration)과 React 18의 선택적 하이드레이션(Selective Hydration)은 내부적으로 DOM을 파싱하고 우선순위를 부여하는 메커니즘에 있어서 어떤 차이가 있는가?
|
||||
- SSR 환경에서 사용자 세션 정보나 전역 상태를 다룰 때, 요청 간 상태 오염(State Pollution)을 완벽하게 격리하기 위한 프레임워크별(예: Next.js vs Pinia) 메모리 관리 패턴은 무엇인가?
|
||||
- React Server Components와 SSR을 동시에 적용하는 아키텍처에서, 에러 바운더리(Error Boundaries)와 Suspense를 활용한 스트리밍 SSR의 실패 복구(Fallback) 메커니즘은 어떻게 작동하는가?
|
||||
- 프론트엔드 서버가 HTML을 미리 렌더링하는 SSG(Static Site Generation) 방식과 요청 시점에 렌더링하는 온디맨드 SSR 방식은 클라우드 환경의 콜드 스타트 및 캐싱 전략에 어떤 영향을 미치는가?
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<h1>Products</h1>
|
||||
<Suspense fallback={<div>매 loading…</div>}>
|
||||
<ProductGrid />
|
||||
</Suspense>
|
||||
</main>
|
||||
);
|
||||
}
|
||||
|
||||
### Practical Application Contexts
|
||||
// app/product-grid.tsx (RSC, runs on server)
|
||||
import { db } from "@/lib/db";
|
||||
|
||||
- **Implementation:** Next.js나 Vue(Nuxt) 프레임워크를 활용하여 초기 로딩이 중요한 전자상거래 사이트, 미디어 플랫폼 등의 화면을 서버에서 미리 렌더링하여 제공합니다. Vue 3.5 기반 프로젝트에서는 `useId()`를 사용해 SSR과 클라이언트 간의 하이드레이션 ID 불일치를 해결합니다 [15, 23].
|
||||
- **System Design:** 백엔드 데이터베이스와 클라이언트 사이의 렌더링 부하를 조율하기 위해, 초기 UI 셸(Shell)과 필수 데이터를 Node.js 같은 프론트엔드 서버에서 결합하여 반환하도록 설계합니다 [2, 24].
|
||||
- **Operation / Maintenance:** 프로덕션 서버 운영 시 SSR 런타임의 메모리 누수나 응답 지연(Latency)을 지속적으로 모니터링해야 하며, 스토어 상태가 사용자 요청 간에 안전하게 격리되도록 지속적으로 구조를 관리해야 합니다 [19, 20].
|
||||
- **Learning Path:** 자바스크립트가 무거워지면서 발생한 CSR의 한계를 먼저 이해한 뒤, SSR의 도입 배경 -> 하이드레이션 메커니즘 -> 하이드레이션 최적화 기술(선택적/지연) -> 서버 컴포넌트(RSC)로 이어지는 렌더링 패러다임의 진화 과정을 학습합니다 [5, 7, 8, 13].
|
||||
- **My Project Relevance:** SEO가 매우 중요하고 첫 화면 페인팅 속도(FCP)가 비즈니스 전환율에 직결되는 프로젝트나, 대규모 자바스크립트 번들 사이즈를 줄이면서도 복잡한 인터랙티브 UI를 렌더링해야 하는 시스템에 최우선으로 도입을 검토할 수 있습니다 [1, 23, 25].
|
||||
|
||||
### Adjacent Topics
|
||||
|
||||
- [[Static Site Generation (SSG)]]
|
||||
- 확장 방향: SSR이 클라이언트의 요청이 발생한 시점(On-demand)에 서버에서 HTML을 렌더링하는 방식이라면, SSG는 빌드 시점(Compile-time)에 HTML을 사전 렌더링하여 정적 파일로 서빙하는 전략입니다. 두 방식의 장단점과 렌더링 시점을 비교하여 웹 성능 최적화의 폭을 넓힐 수 있습니다 [24].
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
- Raw Source: 00_Raw/2026-05-03/Server Side Rendering (SSR).md
|
||||
---
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
export async function ProductGrid() {
|
||||
const products = await db.product.findMany({ take: 20 });
|
||||
return (
|
||||
<ul>
|
||||
{products.map((p) => <li key={p.id}>{p.name}</li>)}
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Partial Prerendering (PPR)
|
||||
```tsx
|
||||
// app/dashboard/page.tsx
|
||||
export const experimental_ppr = true;
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
import { Suspense } from "react";
|
||||
import { StaticHeader } from "./header";
|
||||
import { LiveMetrics } from "./metrics";
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
export default function Page() {
|
||||
return (
|
||||
<>
|
||||
<StaticHeader /> {/* prerendered */}
|
||||
<Suspense fallback={<MetricsSkeleton />}>
|
||||
<LiveMetrics /> {/* dynamic, streamed */}
|
||||
</Suspense>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### ISR with revalidate
|
||||
```tsx
|
||||
// app/posts/[slug]/page.tsx
|
||||
export const revalidate = 60; // every 60s
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
export default async function Page({
|
||||
params,
|
||||
}: { params: Promise<{ slug: string }> }) {
|
||||
const { slug } = await params;
|
||||
const post = await fetch(`https://api.example.com/posts/${slug}`,
|
||||
{ next: { revalidate: 60, tags: [`post:${slug}`] } }).then((r) => r.json());
|
||||
return <article>{post.title}</article>;
|
||||
}
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### On-demand revalidation
|
||||
```typescript
|
||||
// app/api/revalidate/route.ts
|
||||
import { revalidateTag } from "next/cache";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const { tag } = await req.json();
|
||||
revalidateTag(tag);
|
||||
return Response.json({ ok: true });
|
||||
}
|
||||
```
|
||||
|
||||
### Pure React 19 streaming SSR
|
||||
```typescript
|
||||
// server.ts
|
||||
import { renderToReadableStream } from "react-dom/server";
|
||||
import App from "./App";
|
||||
|
||||
export default async function handler(req: Request): Promise<Response> {
|
||||
const stream = await renderToReadableStream(<App url={req.url} />, {
|
||||
bootstrapModules: ["/client.js"],
|
||||
onError: (err) => console.error(err),
|
||||
});
|
||||
await stream.allReady; // remove for true streaming
|
||||
return new Response(stream, {
|
||||
headers: { "content-type": "text/html" },
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Client hydration entry
|
||||
```typescript
|
||||
// client.ts
|
||||
import { hydrateRoot } from "react-dom/client";
|
||||
import App from "./App";
|
||||
|
||||
hydrateRoot(document, <App url={location.href} />);
|
||||
```
|
||||
|
||||
### Cache headers for SSR
|
||||
```typescript
|
||||
// app/api/data/route.ts
|
||||
export async function GET() {
|
||||
return Response.json(
|
||||
{ data: 42 },
|
||||
{
|
||||
headers: {
|
||||
"Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
|
||||
},
|
||||
},
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Server-only utility
|
||||
```typescript
|
||||
// lib/server-only.ts
|
||||
import "server-only"; // 매 import in client component throws
|
||||
|
||||
import { db } from "./db";
|
||||
|
||||
export async function loadSecret() {
|
||||
return db.secret.findFirst();
|
||||
}
|
||||
```
|
||||
|
||||
### Edge runtime SSR
|
||||
```typescript
|
||||
// app/page.tsx
|
||||
export const runtime = "edge";
|
||||
|
||||
export default async function Page() {
|
||||
const data = await fetch("https://api.example.com/edge").then((r) => r.json());
|
||||
return <pre>{JSON.stringify(data)}</pre>;
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Static marketing page | SSG (`generateStaticParams`) |
|
||||
| Per-user dynamic | SSR / RSC |
|
||||
| Mostly static + small dynamic | **PPR** |
|
||||
| Data refreshes minutes-scale | ISR with revalidate |
|
||||
| Internal app, no SEO | CSR (Vite SPA) sufficient |
|
||||
| Low latency global | Edge runtime SSR |
|
||||
|
||||
**기본값**: Next.js 15 App Router + RSC + Suspense streaming + PPR where applicable.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Rendering Strategies]] · [[Web Performance]]
|
||||
- 변형: [[CSR]] · [[SSG]] · [[ISR]] · [[PPR]] · [[Streaming SSR]]
|
||||
- 응용: [[Next.js App Router]] · [[Remix]] · [[SvelteKit]] · [[Nuxt]]
|
||||
- Adjacent: [[React Server Components]] · [[Hydration]] · [[Edge Functions]] · [[Suspense]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: rendering strategy 결정, SEO + first paint 최적화, RSC + Suspense 설계.
|
||||
**언제 X**: 매 internal admin tool with auth-only access (CSR 충분), 매 매우 dynamic real-time app (WebSocket-driven).
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **SSR everything**: 매 unnecessary server compute. 매 marketing page → SSG.
|
||||
- **No streaming**: 매 await all data → blank for 5s. 매 Suspense + streaming.
|
||||
- **Hydration mismatch**: server `Date.now()` vs client → 매 warning. `suppressHydrationWarning` 또는 client-only render.
|
||||
- **Secret in client component**: 매 env var leak. `server-only` import.
|
||||
- **Massive RSC payload**: 매 props 에 huge JSON. 매 boundary 재설계.
|
||||
- **Forgetting cache tags**: ISR 인데 invalidation 못 함.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Next.js 15 docs, React 19 docs, Vercel blog 2026).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — SSR full content |
|
||||
|
||||
Reference in New Issue
Block a user