집가서마저ㅇ

Author: chan9yu

CLAUDE.md

@@ -0,0 +1 @@
+- 노드는 ㅂ무조건 22버전으로 실행! nvm use

docs/msw-server-integration.md

@@ -0,0 +1,153 @@
+# MSW 서버 환경 통합 가이드
+
+## 개요
+
+본 프로젝트는 서버사이드 렌더링(SSR) 환경에서도 MSW(Mock Service Worker)를 활용하여 일관된 API 모킹 환경을 구성하고 있습니다. 이 문서는 왜 서버 환경을 고려한 MSW를 구축했는지, 그리고 어떻게 동작하는지 설명합니다.
+
+## 왜 서버용 MSW가 필요한가?
+
+### 1. SSR에서의 API 호출 필요성
+
+SSR 환경에서는 초기 페이지 렌더링 시 서버에서도 데이터를 가져와야 합니다:
+
+```javascript
+// server.js
+const rendered = await render(url, req.query);
+const html = template
+  .replace(`<!--app-html-->`, rendered.html ?? "")
+  .replace(`<!--app-data-->`, 
+    `<script>window.__INITIAL_DATA__ = ${JSON.stringify(rendered.data)};</script>`
+  );
+```
+
+### 2. 백엔드 의존성 제거
+
+실제 백엔드 API 서버 없이도 풀스택 개발이 가능하도록:
+- 개발 환경에서 즉시 시작 가능
+- 백엔드 개발과 독립적으로 프론트엔드 개발 진행
+- 테스트 환경에서 안정적인 데이터 제공
+
+### 3. 클라이언트-서버 데이터 일관성
+
+동일한 MSW 핸들러를 클라이언트와 서버에서 공유하여:
+- 브라우저에서의 fetch와 서버에서의 fetch가 동일한 응답 받음
+- 하이드레이션 과정에서 데이터 불일치 방지
+- 개발 환경의 예측 가능성 향상
+
+## 구현 구조
+
+### 1. MSW 핸들러 설정
+
+```javascript
+// src/mocks/handlers.js
+export const handlers = [
+  // 와일드카드 패턴으로 서버에서의 절대 URL도 매칭
+  http.get("*/api/products", async ({ request }) => {
+    const url = new URL(request.url);
+    // 쿼리 파라미터 처리 로직
+    return HttpResponse.json(filteredData);
+  }),
+  
+  http.get("*/api/products/:id", ({ params }) => {
+    // 상품 상세 정보 반환
+  }),
+  
+  http.get("*/api/categories", async () => {
+    // 카테고리 목록 반환
+  })
+];
+```
+
+**주요 변경사항:**
+- `/api/products` → `*/api/products`: 서버에서 절대 URL 호출 시에도 매칭
+- JSON imports with assertion: `import items from "./items.json" with { type: "json" }`
+
+### 2. 서버용 MSW 설정
+
+```javascript
+// src/mocks/node.js
+import { setupServer } from "msw/node";
+import { handlers } from "./handlers.js";
+
+export const mswServer = setupServer(...handlers);
+```
+
+### 3. 서버 통합
+
+```javascript
+// server.js
+import { mswServer } from "./src/mocks/node.js";
+
+// MSW 서버 시작
+mswServer.listen({
+  onUnhandledRequest: "bypass", // 모킹되지 않은 요청은 그대로 통과
+});
+
+// Express 서버 시작
+app.listen(port, () => {
+  console.log(`Vanilla Server started at http://localhost:${port}`);
+});
+```
+
+## 데이터 플로우
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant SSR Server
+    participant MSW Server
+    participant Express App
+
+    Browser->>Express App: GET / (페이지 요청)
+    Express App->>SSR Server: render(url, query)
+    SSR Server->>MSW Server: fetch("/api/products")
+    MSW Server->>SSR Server: 모킹된 데이터 응답
+    SSR Server->>Express App: { html, head, data }
+    Express App->>Browser: 완성된 HTML + window.__INITIAL_DATA__
+    
+    Note over Browser: 클라이언트에서 하이드레이션
+    Browser->>MSW Server: fetch("/api/products") (클라이언트 요청)
+    MSW Server->>Browser: 동일한 모킹된 데이터
+```
+
+## 장점
+
+### 1. 개발 생산성
+- 백엔드 API 개발 완료를 기다리지 않고 프론트엔드 개발 진행
+- 로컬 환경에서 즉시 실행 가능한 풀스택 애플리케이션
+
+### 2. 테스트 안정성
+- 외부 API 의존성 없는 안정적인 테스트 환경
+- 일관된 테스트 데이터로 예측 가능한 테스트 결과
+
+### 3. 개발 환경 일관성
+- 서버와 클라이언트에서 동일한 API 응답
+- SSR과 CSR 간의 데이터 불일치 문제 해결
+
+## 주의사항
+
+### 1. URL 패턴 매칭
+서버에서는 절대 URL로 API를 호출하므로 핸들러에서 와일드카드 패턴 사용:
+```javascript
+// ❌ 서버에서 동작하지 않음
+http.get("/api/products", ...)
+
+// ✅ 서버와 클라이언트 모두 동작
+http.get("*/api/products", ...)
+```
+
+### 2. MSW 서버 생명주기
+- Express 서버 시작 전에 MSW 서버를 먼저 시작
+- 애플리케이션 종료 시 MSW 서버도 적절히 정리
+
+### 3. 환경 분리
+프로덕션 환경에서는 MSW를 비활성화하고 실제 API 사용:
+```javascript
+if (process.env.NODE_ENV !== "production") {
+  mswServer.listen({ onUnhandledRequest: "bypass" });
+}
+```
+
+## 결론
+
+서버용 MSW 통합을 통해 개발 환경에서 완전한 풀스택 애플리케이션을 구축할 수 있으며, SSR과 CSR 간의 데이터 일관성을 보장할 수 있습니다. 이는 특히 백엔드 개발과 독립적으로 프론트엔드 개발을 진행해야 하는 상황에서 매우 유용한 접근 방식입니다.

docs/ssr-hydration-guide.md

@@ -0,0 +1,136 @@
+# SSR Hydration Guide
+
+## window.**INITIAL_DATA**의 역할
+
+`window.__INITIAL_DATA__`는 서버사이드 렌더링(SSR)과 클라이언트사이드 하이드레이션(Hydration) 사이의 데이터 동기화를 담당하는 핵심 메커니즘입니다.
+
+## 동작 원리
+
+### 1. 서버사이드 렌더링
+
+```javascript
+// main-server.js
+async function renderHomePage(query) {
+  await loadProductsAndCategories();
+  const initialData = productStore.getState();
+
+  setServerData({
+    pathname: "/",
+    query,
+    params: {},
+    data: initialData,
+  });
+
+  return {
+    head: `<title>쇼핑몰</title>`,
+    html: HomePage(), // 서버에서 HTML 생성
+    data: initialData, // 클라이언트로 전달될 데이터
+  };
+}
+```
+
+### 2. HTML에 데이터 주입
+
+서버 응답에서 HTML에 다음과 같은 스크립트 태그가 포함됩니다:
+
+```html
+<script>
+  window.__INITIAL_DATA__ = {
+    products: [...],
+    categories: [...],
+    loading: false,
+    error: null
+  };
+</script>
+```
+
+### 3. 클라이언트 하이드레이션
+
+```javascript
+// withServer.js
+export const withServer = (options, page) => {
+  const pageWithSSR = () => {
+    const pageParams = isServer()
+      ? currentServerData // 서버: 설정된 데이터 사용
+      : {
+          pathname: window.location.pathname,
+          query: routerInstance.query,
+          params: routerInstance.params,
+          data: window.__INITIAL_DATA__, // 클라이언트: 주입된 데이터 사용
+        };
+    return page(pageParams);
+  };
+
+  return pageWithSSR;
+};
+```
+
+## 하이드레이션 과정
+
+1. **서버**: 초기 데이터로 정적 HTML 생성
+2. **브라우저**: HTML 로드 및 `window.__INITIAL_DATA__` 파싱
+3. **JavaScript**: 같은 초기 데이터로 컴포넌트 활성화
+4. **결과**: 서버 HTML과 클라이언트 렌더링이 일치하여 매끄러운 하이드레이션
+
+## 주요 이점
+
+### ✅ 데이터 일관성
+
+- 서버와 클라이언트가 동일한 초기 상태를 가짐
+- Hydration mismatch 방지
+
+### ✅ 성능 최적화
+
+- 초기 페이지 로드 시 추가 API 호출 불필요
+- 사용자에게 즉시 완전한 페이지 표시
+
+### ✅ SEO 친화적
+
+- 서버에서 완전한 HTML 제공
+- 검색 엔진이 모든 콘텐츠 인덱싱 가능
+
+## 코드 예시
+
+### 페이지 컴포넌트에서의 사용
+
+```javascript
+const HomePageComponent = ({ query, data }) => {
+  // 서버: data 파라미터에서 초기 데이터 사용
+  // 클라이언트: window.__INITIAL_DATA__에서 자동으로 가져온 데이터 사용
+  const productState = data || productStore.getState();
+
+  return PageWrapper({
+    children: `
+      ${SearchBar({ ...query, categories: productState.categories })}
+      ${ProductList({ products: productState.products })}
+    `,
+  });
+};
+```
+
+### 라이프사이클에서의 활용
+
+```javascript
+export const HomePage = withServer(
+  {},
+  withLifecycle(
+    {
+      onMount: () => {
+        // 클라이언트에서만 실행
+        const initialData = window.__INITIAL_DATA__;
+        console.log("하이드레이션 데이터:", initialData);
+
+        // 필요시 추가 데이터 로드
+        loadProductsAndCategories();
+      },
+    },
+    HomePageComponent,
+  ),
+);
+```
+
+## 주의사항
+
+- `window.__INITIAL_DATA__`는 클라이언트에서만 사용 가능
+- 서버 환경에서는 `setServerData()`로 설정된 데이터 사용
+- 초기 데이터 사용 후 `delete window.__INITIAL_DATA__`로 메모리 정리 권장