@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/perf/10-optimize-lcp.md

@@ -0,0 +1,201 @@
+---
+title: LCP 최적화 심화 — 4가지 하위 구성 요소별 전략
+source: https://web.dev/articles/optimize-lcp
+fetched: 2026-05-18
+category: images
+---
+
+## LCP 목표
+
+**Good**: 75번째 백분위수 기준 ≤ 2.5초
+**Needs Improvement**: 2.5 ~ 4.0초
+**Poor**: > 4.0초
+
+---
+
+## LCP = 4가지 하위 구성 요소의 합
+
+```
+LCP = TTFB + Resource Load Delay + Resource Load Duration + Element Render Delay
+```
+
+| 구성 요소 | 이상적 비중 | 의미 |
+|-----------|------------|------|
+| **TTFB** | ~40% | 서버 최초 바이트 응답 시간 |
+| **Resource Load Delay** | <10% | TTFB 종료 ~ LCP 리소스 로딩 시작 |
+| **Resource Load Duration** | ~40% | 실제 리소스 전송 시간 |
+| **Element Render Delay** | <10% | 리소스 완료 ~ 화면에 그려지는 시간 |
+
+**핵심 원칙**: 어느 단계에도 "아무것도 로딩되지 않는" 구간을 만들지 마라.
+두 리소스(HTML + LCP 리소스)가 동시에 로딩되는 것이 이상적.
+
+---
+
+## 최적화 우선순위 1: Resource Load Delay 제거
+
+### 문제: LCP 이미지가 늦게 발견됨
+
+```html
+<!-- BAD: CSS background (preload scanner 미탐지) -->
+<div class="hero"></div>
+```
+```css
+.hero { background-image: url('/hero.webp'); }
+```
+
+```html
+<!-- GOOD: HTML에 직접 포함 (preload scanner 탐지) -->
+<img src="/hero.webp" alt="히어로" fetchpriority="high">
+```
+
+### 문제: LCP 이미지가 JS에서만 참조됨
+
+```html
+<!-- GOOD: preload link 추가 -->
+<link rel="preload" fetchpriority="high" as="image"
+  href="/hero.webp" type="image/webp">
+```
+
+### 문제: LCP 이미지에 lazy loading 적용
+
+```html
+<!-- BAD -->
+<img src="/hero.webp" loading="lazy" alt="히어로">
+
+<!-- GOOD -->
+<img src="/hero.webp" loading="eager" fetchpriority="high" alt="히어로">
+```
+
+### fetchpriority 힌트
+
+```html
+<!-- LCP 이미지에 높은 우선순위 -->
+<img fetchpriority="high" src="/hero.webp" alt="히어로">
+
+<!-- 폴드 아래 이미지에 낮은 우선순위 (기본 lazy와 병행 가능) -->
+<img fetchpriority="low" src="/below-fold.jpg" alt="...">
+```
+
+---
+
+## 최적화 우선순위 2: Element Render Delay 제거
+
+### 렌더링 블록 CSS
+
+```html
+<!-- BAD: 큰 외부 CSS 파일이 렌더링 블록 -->
+<link rel="stylesheet" href="/large-styles.css">
+
+<!-- GOOD: 크리티컬 CSS 인라인화 -->
+<style>
+  /* 첫 화면에 필요한 최소한의 CSS만 */
+  .hero { ... }
+</style>
+<!-- 나머지 CSS는 비동기 로드 -->
+<link rel="stylesheet" href="/non-critical.css" media="print"
+  onload="this.media='all'">
+```
+
+### 렌더링 블록 JavaScript
+
+```html
+<!-- BAD: head의 동기 스크립트 -->
+<script src="/analytics.js"></script>
+
+<!-- GOOD: defer 또는 async 사용 -->
+<script src="/analytics.js" defer></script>
+<!-- 또는 크리티컬하지 않으면 body 끝으로 이동 -->
+```
+
+### 서버사이드 렌더링 활용
+
+```javascript
+// SSR: 이미지 src가 초기 HTML에 포함 → preload scanner 탐지 가능
+// CSR: 이미지 src가 JS 실행 후 결정 → Resource Load Delay 증가
+```
+
+### Long Task 방지
+
+```javascript
+// BAD: 메인 스레드를 오래 블록하는 작업
+function heavyCalculation() { /* 200ms+ */ }
+
+// GOOD: 분할 실행
+async function chunkedCalculation(items) {
+  for (const item of items) {
+    processItem(item)
+    // 다음 frame 전에 제어권 반환
+    await scheduler.yield()
+  }
+}
+```
+
+---
+
+## 최적화 우선순위 3: Resource Load Duration 단축
+
+```html
+<!-- 현대 이미지 포맷 사용 -->
+<picture>
+  <source srcset="/hero.avif" type="image/avif">
+  <source srcset="/hero.webp" type="image/webp">
+  <img src="/hero.jpg" alt="히어로">
+</picture>
+
+<!-- 반응형 srcset으로 적절한 크기 제공 -->
+<img
+  srcset="/hero-480.webp 480w, /hero-800.webp 800w, /hero-1200.webp 1200w"
+  sizes="(max-width: 600px) 480px, (max-width: 1000px) 800px, 1200px"
+  src="/hero-1200.webp"
+  alt="히어로"
+  fetchpriority="high">
+```
+
+### CDN / Image CDN 활용
+
+```javascript
+// Cloudinary, Imgix 등 Image CDN은:
+// - 자동 WebP/AVIF 변환
+// - 엣지에서 크기 최적화
+// - 자동 압축
+// URL 패턴 예시
+const optimizedUrl = `https://res.cloudinary.com/demo/image/fetch/w_800,f_auto,q_auto/${originalUrl}`
+```
+
+### 캐싱 정책
+
+```http
+Cache-Control: public, max-age=31536000, immutable
+```
+
+---
+
+## 최적화 우선순위 4: TTFB 단축
+
+- 서버 사이드 렌더링 캐싱 (Vercel Edge Cache, CDN)
+- 불필요한 리다이렉트 제거 (`http://` → `https://`, `www.` 제거)
+- 서버 처리 시간 최소화
+- Edge Function으로 지리적 지연 최소화
+
+---
+
+## 진단 도구
+
+```javascript
+// LCP 하위 구성 요소 측정 (web-vitals 라이브러리)
+import {onLCP} from 'web-vitals/attribution';
+
+onLCP(metric => {
+  const {
+    timeToFirstByte,        // TTFB
+    resourceLoadDelay,      // Resource Load Delay
+    resourceLoadDuration,   // Resource Load Duration
+    elementRenderDelay      // Element Render Delay
+  } = metric.attribution;
+
+  console.log({timeToFirstByte, resourceLoadDelay, resourceLoadDuration, elementRenderDelay});
+});
+```
+
+**실제 사용자 데이터(CrUX)를 랩 데이터(Lighthouse)보다 우선** 확인할 것.
+75번째 백분위수가 2.5초 이하라면 하위 구성 요소 세분화 최적화보다 다른 우선순위를 고려.

package/assets/dev-guide/fe/sources/perf/INDEX.md

@@ -0,0 +1,88 @@
+---
+title: FE 성능 가이드 — 문서 인덱스
+fetched: 2026-05-18
+category: index
+---
+
+# FE 성능 가이드 소스 문서 인덱스
+
+2024-2026 최신 웹 성능 트렌드 기반. Vercel + web.dev + Chrome Developers 공식 문서.
+
+---
+
+## 문서 목록
+
+### Core Web Vitals (web-vitals)
+
+| 파일 | 주제 | 핵심 임계값 |
+|------|------|------------|
+| [01-core-web-vitals.md](./01-core-web-vitals.md) | LCP·INP·CLS 전체 개요 | LCP≤2.5s, INP≤200ms, CLS≤0.1 |
+| [02-inp.md](./02-inp.md) | INP 심화 — FID 대체 신 지표 (2024) | ≤200ms Good, >500ms Poor |
+| [03-lcp-cls.md](./03-lcp-cls.md) | LCP·CLS 최신 가이드라인 + 4 하위 구성 요소 | LCP≤2.5s, CLS≤0.1 |
+
+### 네비게이션 (navigation)
+
+| 파일 | 주제 | 브라우저 지원 |
+|------|------|--------------|
+| [04-speculation-rules.md](./04-speculation-rules.md) | Speculation Rules API — 즉시 페이지 전환 | Chrome 109+, Edge 109+ |
+| [05-view-transitions.md](./05-view-transitions.md) | View Transitions API — 페이지 전환 애니메이션 | Same-doc: Chrome 111+; Cross-doc: Chrome 126+ |
+
+### Next.js 캐싱·렌더링 (caching)
+
+| 파일 | 주제 | 버전 |
+|------|------|------|
+| [06-nextjs-caching.md](./06-nextjs-caching.md) | App Router 캐싱 전략 (fetch, unstable_cache, use cache, React cache) | Next.js 16 |
+| [07-server-components.md](./07-server-components.md) | Server vs Client Components 선택 기준 + 렌더링 흐름 | Next.js 16 |
+| [08-ppr.md](./08-ppr.md) | PPR (Partial Prerendering) — 정적 shell + 동적 스트리밍 | Next.js 16 |
+
+### 이미지 최적화 (images)
+
+| 파일 | 주제 | 핵심 |
+|------|------|------|
+| [09-nextjs-image.md](./09-nextjs-image.md) | next/image 컴포넌트 전체 props + 최적화 패턴 | preload, fill, sizes, placeholder |
+| [10-optimize-lcp.md](./10-optimize-lcp.md) | LCP 4 하위 구성 요소별 최적화 심화 | fetchpriority, SSR, CDN |
+
+---
+
+## 카테고리별 빠른 참조
+
+### 임계값 요약
+
+| 지표 | Good | Needs Improvement | Poor |
+|------|------|-------------------|------|
+| **LCP** | ≤ 2.5초 | 2.5 ~ 4.0초 | > 4.0초 |
+| **INP** | ≤ 200ms | 201 ~ 500ms | > 500ms |
+| **CLS** | ≤ 0.1 | 0.1 ~ 0.25 | > 0.25 |
+
+기준: 75번째 백분위수 (모바일 + 데스크톱)
+
+### 2024 주요 변경사항
+
+1. **INP 공식 Core Web Vital 승격** (2024년 3월) — FID 은퇴
+2. **Cross-Document View Transitions** 지원 (Chrome 126, 2024년)
+3. **Next.js 16 cacheComponents** — PPR + use cache + dynamicIO 통합 플래그
+
+### 도구 추천
+
+| 목적 | 도구 |
+|------|------|
+| 실사용자 데이터 | Chrome UX Report, PageSpeed Insights (Field Data) |
+| 랩 측정 | Lighthouse, WebPageTest, Chrome DevTools |
+| JS 측정 | `web-vitals` 라이브러리 (`onLCP`, `onINP`, `onCLS`) |
+| INP attribution | `web-vitals/attribution` (하위 구성 요소 세분화) |
+
+---
+
+## 출처
+
+- https://web.dev/articles/vitals
+- https://web.dev/articles/inp
+- https://web.dev/articles/lcp
+- https://web.dev/articles/cls
+- https://web.dev/articles/optimize-lcp
+- https://developer.chrome.com/docs/web-platform/prerender-pages
+- https://developer.chrome.com/docs/web-platform/view-transitions
+- https://nextjs.org/docs/app/building-your-application/caching
+- https://nextjs.org/docs/app/building-your-application/rendering/server-components
+- https://nextjs.org/docs/app/api-reference/next-config-js/ppr
+- https://nextjs.org/docs/app/api-reference/components/image

package/assets/dev-guide/fe/sources/react/INDEX.md

@@ -0,0 +1,41 @@
+---
+title: React 19 FE 가이드 문서 인덱스
+fetched: 2026-05-18
+---
+
+# React 19 핵심 문서
+
+| 파일 | 제목 | 카테고리 | 소스 |
+|------|------|----------|------|
+| [use-hook.md](./use-hook.md) | `use()` Hook | api | https://react.dev/reference/react/use |
+| [use-action-state.md](./use-action-state.md) | `useActionState` | api | https://react.dev/reference/react/useActionState |
+| [use-optimistic.md](./use-optimistic.md) | `useOptimistic` | api | https://react.dev/reference/react/useOptimistic |
+| [use-form-status.md](./use-form-status.md) | `useFormStatus` / `<form action={}>` | api | https://react.dev/reference/react-dom/hooks/useFormStatus |
+| [server-components.md](./server-components.md) | Server Components | rsc | https://react.dev/reference/rsc/server-components |
+| [server-functions.md](./server-functions.md) | Server Functions (`'use server'` / `'use client'`) | rsc | https://react.dev/reference/rsc/server-functions |
+| [suspense.md](./suspense.md) | Suspense & Streaming | suspense | https://react.dev/reference/react/Suspense |
+| [react-compiler.md](./react-compiler.md) | React Compiler (자동 메모이제이션) | compiler | https://react.dev/learn/react-compiler |
+| [no-effect-patterns.md](./no-effect-patterns.md) | Effect 회피 패턴 | patterns | https://react.dev/learn/you-might-not-need-an-effect |
+| [keeping-components-pure.md](./keeping-components-pure.md) | 컴포넌트 순수성 유지 | patterns | https://react.dev/learn/keeping-components-pure |
+
+## 카테고리별 분류
+
+### API (React 19 신 Hook)
+- `use()` — Promise/Context 읽기, 조건부 호출 가능
+- `useActionState` — Action 결과로 state 관리, form 제출
+- `useOptimistic` — 낙관적 UI 업데이트
+- `useFormStatus` — 부모 form 제출 상태 읽기
+
+### RSC (React Server Components)
+- Server Components — 서버 전용 렌더링, async/await 직접 사용
+- Server Functions — `"use server"` 함수, form action에 직접 전달
+
+### Suspense & Streaming
+- 중첩 Suspense로 순차 스트리밍, startTransition으로 fallback 방지
+
+### Compiler
+- 자동 메모이제이션 — `useMemo`/`useCallback` 수동 작성 불필요
+
+### Patterns (리뷰 핵심)
+- Effect 회피 패턴 — 불필요한 Effect 제거
+- 컴포넌트 순수성 — 렌더 중 side effect 금지

package/assets/dev-guide/fe/sources/react/keeping-components-pure.md

@@ -0,0 +1,135 @@
+---
+title: Keeping Components Pure (컴포넌트 순수성 유지)
+source: https://react.dev/learn/keeping-components-pure
+fetched: 2026-05-18
+category: patterns
+react_version: 19
+---
+
+## 개요
+
+React는 모든 컴포넌트가 순수 함수라고 가정. 같은 입력에 항상 같은 JSX를 반환해야 함.
+
+**순수 컴포넌트의 두 원칙:**
+1. **자기 일에만 집중** — 호출 전 존재하던 객체/변수를 변경하지 않음
+2. **같은 입력 → 같은 출력** — 항상 동일한 결과 반환
+
+---
+
+## 순수 컴포넌트 예시
+
+```js
+function Recipe({ drinkers }) {
+  return (
+    <ol>
+      <li>Boil {drinkers} cups of water.</li>
+      <li>Add {drinkers} spoons of tea and {0.5 * drinkers} spoons of spice.</li>
+      <li>Add {0.5 * drinkers} cups of milk to boil and sugar to taste.</li>
+    </ol>
+  );
+}
+```
+
+`drinkers={2}`이면 항상 "2 cups of water" JSX 반환.
+
+---
+
+## 불순 컴포넌트 (Side Effect During Render)
+
+❌ 외부 변수 변경 — 예측 불가:
+```js
+let guest = 0;
+
+function Cup() {
+  guest = guest + 1; // 🚩 외부 변수 변경
+  return <h2>Tea cup for guest #{guest}</h2>;
+}
+```
+
+같은 컴포넌트를 여러 번 호출하면 다른 결과 → 버그.
+
+✅ props로 데이터 전달:
+```js
+function Cup({ guest }) {
+  return <h2>Tea cup for guest #{guest}</h2>;
+}
+
+export default function TeaSet() {
+  return (
+    <>
+      <Cup guest={1} />
+      <Cup guest={2} />
+      <Cup guest={3} />
+    </>
+  );
+}
+```
+
+---
+
+## Local Mutation은 안전
+
+렌더링 중 **직접 생성한** 변수의 변경은 안전 ("local mutation"):
+
+```js
+export default function TeaGathering() {
+  const cups = []; // 이 렌더에서 생성
+  for (let i = 1; i <= 12; i++) {
+    cups.push(<Cup key={i} guest={i} />); // ✅ local mutation, 순수성 유지
+  }
+  return cups;
+}
+```
+
+외부 코드가 이 변수를 알 수 없으므로 순수성 유지.
+
+---
+
+## Side Effect가 허용되는 위치
+
+**1. 이벤트 핸들러 (권장):**
+```js
+function Button() {
+  const handleClick = () => {
+    updateDatabase(); // ✅ 이벤트 핸들러 내부
+  };
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+**2. useEffect (최후 수단):**
+```js
+useEffect(() => {
+  document.title = "Updated"; // ✅ 렌더링 후 실행
+}, []);
+```
+
+렌더 함수 자체에서는 side effect 금지.
+
+---
+
+## React StrictMode
+
+개발 모드에서 컴포넌트 함수를 **두 번** 호출하여 불순 컴포넌트 감지:
+- 순수 함수: 두 번 호출해도 같은 결과
+- 불순 함수: 버그가 드러남
+
+---
+
+## 순수성이 가능하게 하는 것
+
+- **서버 사이드 렌더링**: 같은 입력 → 같은 결과 보장
+- **성능 최적화**: 입력이 변경되지 않으면 캐시된 결과 재사용
+- **렌더 인터럽트 안전**: 데이터 변경 시 새 렌더 재시작 가능
+
+---
+
+## 핵심 규칙 요약
+
+| 규칙 | 설명 |
+|------|------|
+| 외부 변수 변경 금지 | 렌더 전 존재하던 변수 수정 불가 |
+| props/state/context는 읽기 전용 | 직접 수정 불가 |
+| local mutation은 허용 | 렌더 중 새로 생성한 변수만 |
+| side effect 위치 | 이벤트 핸들러 또는 `useEffect` |
+| 독립적 렌더 | 컴포넌트는 렌더 중 다른 컴포넌트와 협력하지 않음 |

package/assets/dev-guide/fe/sources/react/no-effect-patterns.md

@@ -0,0 +1,183 @@
+---
+title: You Might Not Need an Effect (Effect 회피 패턴)
+source: https://react.dev/learn/you-might-not-need-an-effect
+fetched: 2026-05-18
+category: patterns
+react_version: 19
+---
+
+## 개요
+
+Effect는 React 패러다임의 **탈출구** — 외부 시스템과 동기화할 때만 사용. 많은 경우 더 간단한 대안이 있음.
+
+**Effect가 필요 없는 두 가지 주요 케이스:**
+1. 렌더링을 위한 데이터 변환
+2. 사용자 이벤트 처리
+
+---
+
+## 패턴별 가이드
+
+### 1. 렌더링용 데이터 변환 → 렌더 중 계산
+
+❌ 피할 것:
+```js
+function Form() {
+  const [firstName, setFirstName] = useState('Taylor');
+  const [lastName, setLastName] = useState('Swift');
+  const [fullName, setFullName] = useState('');
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName);
+  }, [firstName, lastName]);
+}
+```
+
+✅ 렌더 중 직접 계산:
+```js
+function Form() {
+  const [firstName, setFirstName] = useState('Taylor');
+  const [lastName, setLastName] = useState('Swift');
+  const fullName = firstName + ' ' + lastName; // Effect 불필요
+}
+```
+
+---
+
+### 2. 비용이 큰 계산 → useMemo
+
+```js
+function TodoList({ todos, filter }) {
+  const visibleTodos = useMemo(
+    () => getFilteredTodos(todos, filter),
+    [todos, filter]
+  );
+}
+```
+
+---
+
+### 3. prop 변경 시 state 리셋 → key 사용
+
+```js
+export default function ProfilePage({ userId }) {
+  return (
+    <Profile
+      userId={userId}
+      key={userId} // userId가 변경되면 컴포넌트 전체 리셋
+    />
+  );
+}
+```
+
+---
+
+### 4. prop 기반 state 조정 → 렌더 중 계산
+
+```js
+function List({ items }) {
+  const [selectedId, setSelectedId] = useState(null);
+  // Effect 없이 렌더 중 계산
+  const selection = items.find(item => item.id === selectedId) ?? null;
+}
+```
+
+---
+
+### 5. 이벤트 핸들러 간 로직 공유 → 함수 추출
+
+❌ 피할 것:
+```js
+useEffect(() => {
+  if (product.isInCart) {
+    showNotification(`Added ${product.name} to cart!`);
+  }
+}, [product]);
+```
+
+✅ 이벤트 핸들러에서 직접 처리:
+```js
+function ProductPage({ product, addToCart }) {
+  function buyProduct() {
+    addToCart(product);
+    showNotification(`Added ${product.name} to cart!`);
+  }
+
+  function handleBuyClick() {
+    buyProduct();
+  }
+
+  function handleCheckoutClick() {
+    buyProduct();
+    navigateTo('/checkout');
+  }
+}
+```
+
+---
+
+### 6. state 업데이트 체인 → 이벤트 핸들러에서 한 번에
+
+❌ Effect 체인 (N번 리렌더):
+```js
+useEffect(() => {
+  if (card.gold) setGoldCardCount(c => c + 1);
+}, [card]);
+
+useEffect(() => {
+  if (goldCardCount > 3) setRound(r => r + 1);
+}, [goldCardCount]);
+```
+
+✅ 이벤트 핸들러에서 한 번에:
+```js
+function handlePlaceCard(nextCard) {
+  setCard(nextCard);
+  if (nextCard.gold) {
+    if (goldCardCount < 3) {
+      setGoldCardCount(goldCardCount + 1);
+    } else {
+      setGoldCardCount(0);
+      setRound(round + 1);
+    }
+  }
+}
+```
+
+---
+
+### 7. 부모에게 변경 알리기 → 같은 이벤트에서 처리
+
+```js
+function Toggle({ onChange }) {
+  const [isOn, setIsOn] = useState(false);
+
+  function updateToggle(nextIsOn) {
+    setIsOn(nextIsOn);
+    onChange(nextIsOn); // Effect 아닌 이벤트 핸들러에서 호출
+  }
+}
+```
+
+---
+
+## Effect가 실제로 필요한 경우
+
+- **외부 시스템 동기화** (jQuery 위젯, 브라우저 API)
+- **데이터 페칭** (race condition 처리를 위한 cleanup 필요)
+- **외부 스토어 구독** → `useSyncExternalStore` 사용
+
+---
+
+## 요약 표
+
+| 패턴 | ❌ Effect 사용 | ✅ 대안 |
+|------|--------------|---------|
+| 데이터 변환 | state + Effect | 렌더 중 계산 |
+| 비싼 계산 | state + Effect | `useMemo` |
+| prop 변경 시 리셋 | Effect에서 `setState` | `key` prop |
+| 사용자 이벤트 처리 | Effect | 이벤트 핸들러 |
+| 부모에게 변경 알림 | Effect | 이벤트 핸들러 |
+| 외부 동기화 | (적절한 경우) | Effect 또는 `useSyncExternalStore` |
+
+**황금 규칙:** 컴포넌트가 _표시_되어서 실행해야 하면 Effect, 특정 _인터랙션_ 때문이면 이벤트 핸들러.