@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/perf/06-nextjs-caching.md

@@ -0,0 +1,188 @@
+---
+title: Next.js App Router 캐싱 전략 (Next.js 16 기준)
+source: https://nextjs.org/docs/app/building-your-application/caching
+fetched: 2026-05-18
+category: caching
+---
+
+## 개요
+
+Next.js 16의 캐싱 모델은 `cacheComponents` 플래그 도입으로 재편되었다.
+데이터는 기본 **비캐싱(dynamic)**, 필요한 곳에만 `use cache` 지시어로 캐싱 opt-in.
+
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,  // use cache + PPR 통합 활성화
+}
+
+export default nextConfig
+```
+
+---
+
+## 캐싱 계층 구조
+
+### 1. fetch() 캐싱
+
+```typescript
+// 캐시 저장
+const data = await fetch('https://api.example.com/data', {
+  cache: 'force-cache'
+})
+
+// 캐시 없음 (기본값)
+const data = await fetch('https://api.example.com/data')
+// 또는
+const data = await fetch('https://api.example.com/data', {
+  cache: 'no-store'
+})
+
+// 시간 기반 재검증 (3600초 = 1시간)
+const data = await fetch('https://api.example.com/data', {
+  next: { revalidate: 3600 }
+})
+
+// 태그 기반 온디맨드 재검증
+const data = await fetch('https://api.example.com/users', {
+  next: { tags: ['user'] }
+})
+```
+
+### 2. unstable_cache (non-fetch 함수)
+
+```typescript
+import { unstable_cache } from 'next/cache'
+import { db } from '@/lib/db'
+
+export const getCachedUser = unstable_cache(
+  async (id: string) => {
+    return db.select().from(users).where(eq(users.id, id)).then(r => r[0])
+  },
+  ['user'],           // 캐시 키 prefix
+  {
+    tags: ['user'],
+    revalidate: 3600,
+  }
+)
+```
+
+### 3. use cache 지시어 (cacheComponents 활성화 시)
+
+```typescript
+// 컴포넌트 레벨 캐싱
+async function CachedDashboard() {
+  'use cache'
+  const data = await fetchDashboardData()
+  return <Dashboard data={data} />
+}
+
+// 함수 레벨 캐싱
+async function getCachedData(id: string) {
+  'use cache'
+  return await db.query.findById(id)
+}
+```
+
+### 4. React cache (요청 단위 메모이제이션)
+
+```typescript
+import { cache } from 'react'
+
+// 단일 렌더 패스 내 중복 요청 제거
+export const getPost = cache(async (id: string) => {
+  const post = await db.query.posts.findFirst({
+    where: eq(posts.id, parseInt(id)),
+  })
+  return post
+})
+```
+
+---
+
+## 온디맨드 재검증
+
+### revalidateTag — 태그로 무효화
+
+```typescript
+import { revalidateTag } from 'next/cache'
+
+export async function updateUser(id: string) {
+  await db.update(users).set({ name: 'new' }).where(eq(users.id, id))
+  revalidateTag('user')  // 'user' 태그를 가진 모든 캐시 무효화
+}
+```
+
+### revalidatePath — 경로로 무효화
+
+```typescript
+import { revalidatePath } from 'next/cache'
+
+export async function updatePost() {
+  await db.update(posts)...
+  revalidatePath('/blog')  // /blog 경로의 모든 캐시 무효화
+}
+```
+
+---
+
+## Route Segment Config
+
+```typescript
+// layout.tsx | page.tsx | route.ts
+
+// 항상 동적 렌더링
+export const dynamic = 'force-dynamic'
+
+// 항상 정적 (빌드 시 생성)
+export const dynamic = 'force-static'
+
+// 기본 재검증 주기 설정 (초)
+export const revalidate = 3600
+
+// fetch 캐시 정책 일괄 설정
+export const fetchCache = 'force-cache'
+// 'auto' | 'default-cache' | 'only-cache' | 'force-cache'
+// 'default-no-store' | 'only-no-store' | 'force-no-store'
+```
+
+---
+
+## 데이터 Preload 패턴
+
+```typescript
+// utils/get-item.ts
+import { cache } from 'react'
+import 'server-only'
+
+export const getItem = cache(async (id: string) => {
+  // DB 또는 API 호출
+})
+
+// 블로킹 작업 전에 미리 데이터 로딩 시작
+export const preload = (id: string) => {
+  void getItem(id)
+}
+```
+
+```typescript
+// page.tsx
+import { getItem, preload, checkIsAvailable } from '@/lib/data'
+
+export default async function Page({ params }) {
+  const { id } = await params
+  preload(id)                          // 즉시 데이터 로딩 시작
+  const isAvailable = await checkIsAvailable()  // 병렬 진행
+  return isAvailable ? <Item id={id} /> : null
+}
+```
+
+---
+
+## 재검증 빈도 규칙
+
+- 라우트의 재검증 빈도 = 해당 라우트 내 레이아웃+페이지 중 **가장 낮은 revalidate 값**
+- 개별 fetch가 라우트 기본값보다 낮은 revalidate를 갖고 있으면 그 값이 전체 라우트에 영향
+- `revalidate` 값은 정적으로 분석 가능해야 함 (`revalidate = 600` O, `revalidate = 60 * 10` X)

package/assets/dev-guide/fe/sources/perf/07-server-components.md

@@ -0,0 +1,181 @@
+---
+title: Next.js Server Components & Client Components
+source: https://nextjs.org/docs/app/building-your-application/rendering/server-components
+fetched: 2026-05-18
+category: caching
+---
+
+## 기본 원칙
+
+App Router에서 레이아웃과 페이지는 기본적으로 **Server Component**.
+상호작용·브라우저 API가 필요한 경우에만 `'use client'`로 Client Component 지정.
+
+---
+
+## Server vs Client 선택 기준
+
+| 필요한 것 | 권장 컴포넌트 |
+|-----------|--------------|
+| DB/API 직접 접근 | Server |
+| API 키·시크릿 보호 | Server |
+| JS 번들 크기 최소화 | Server |
+| FCP 개선, 점진적 스트리밍 | Server |
+| `onClick`, `onChange` 등 이벤트 핸들러 | Client |
+| `useState`, `useEffect` | Client |
+| `localStorage`, `window` 등 브라우저 API | Client |
+| 커스텀 훅 (상태 기반) | Client |
+
+---
+
+## 렌더링 흐름
+
+### 서버 측
+1. Server Component → RSC Payload (바이너리 포맷) 생성
+2. Client Component + RSC Payload → HTML prerender
+
+> **RSC Payload**: Server Component 렌더 결과 + Client Component 위치 플레이스홀더 + 참조 파일 경로
+
+### 클라이언트 측 (최초 로드)
+1. HTML → 즉시 non-interactive 프리뷰 표시
+2. RSC Payload → Client/Server 컴포넌트 트리 조정(reconcile)
+3. JavaScript → Client Component 하이드레이션 (인터랙티브)
+
+### 이후 네비게이션
+- RSC Payload prefetch + 캐시 → 즉시 네비게이션
+- Client Component는 클라이언트에서만 렌더 (서버 HTML 없음)
+
+---
+
+## 코드 예시
+
+### 기본 패턴: Server + Client 조합
+
+```tsx
+// app/[id]/page.tsx — Server Component
+import LikeButton from '@/app/ui/like-button'
+import { getPost } from '@/lib/data'
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params
+  const post = await getPost(id)  // 서버에서 직접 DB 접근
+
+  return (
+    <div>
+      <h1>{post.title}</h1>
+      <LikeButton likes={post.likes} />  {/* Client Component에 props 전달 */}
+    </div>
+  )
+}
+```
+
+```tsx
+// app/ui/like-button.tsx — Client Component
+'use client'
+
+import { useState } from 'react'
+
+export default function LikeButton({ likes }: { likes: number }) {
+  const [count, setCount] = useState(likes)
+  return <button onClick={() => setCount(c => c + 1)}>{count} Likes</button>
+}
+```
+
+### JS 번들 최소화 패턴
+
+```tsx
+// app/layout.tsx — Server Component
+import Search from './search'   // Client Component (검색창만)
+import Logo from './logo'       // Server Component (정적)
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <nav>
+        <Logo />    {/* 서버 렌더 */}
+        <Search />  {/* 클라이언트 번들 포함 */}
+      </nav>
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
+### Server를 Client에 children으로 전달
+
+```tsx
+// 'use client' Modal에 Server Component인 Cart를 children으로 전달 가능
+// app/ui/modal.tsx
+'use client'
+export default function Modal({ children }: { children: React.ReactNode }) {
+  return <div>{children}</div>
+}
+
+// app/page.tsx
+import Modal from './ui/modal'
+import Cart from './ui/cart'  // Server Component
+
+export default function Page() {
+  return (
+    <Modal>
+      <Cart />  {/* 서버에서 미리 렌더링됨 */}
+    </Modal>
+  )
+}
+```
+
+---
+
+## Context Provider 패턴
+
+React context는 Server Component에서 직접 사용 불가. Client Component로 감싸기:
+
+```tsx
+// app/theme-provider.tsx
+'use client'
+import { createContext } from 'react'
+
+export const ThemeContext = createContext({})
+
+export default function ThemeProvider({ children }: { children: React.ReactNode }) {
+  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
+}
+```
+
+```tsx
+// app/layout.tsx — Server Component
+import ThemeProvider from './theme-provider'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+        {/* Provider를 트리 가능한 한 깊숙이 배치 → 정적 부분 최적화 */}
+      </body>
+    </html>
+  )
+}
+```
+
+---
+
+## 환경 오염 방지
+
+```javascript
+// lib/data.js — 서버 전용 강제
+import 'server-only'  // 클라이언트에서 import 시 빌드 에러
+
+export async function getData() {
+  const res = await fetch('https://api.example.com', {
+    headers: { authorization: process.env.API_KEY },  // 서버에서만 접근
+  })
+  return res.json()
+}
+```
+
+- `NEXT_PUBLIC_` 접두사 없는 환경변수는 클라이언트 번들에서 빈 문자열로 치환됨
+- 반대로 클라이언트 전용 코드: `client-only` 패키지 사용

package/assets/dev-guide/fe/sources/perf/08-ppr.md

@@ -0,0 +1,133 @@
+---
+title: PPR — Partial Prerendering (부분 프리렌더링)
+source: https://nextjs.org/docs/app/api-reference/next-config-js/ppr
+fetched: 2026-05-18
+category: caching
+---
+
+## 개요
+
+PPR(Partial Prerendering)은 단일 라우트에서 **정적 콘텐츠(HTML shell)**와 **동적 콘텐츠(스트리밍)**를 혼합한다.
+빌드 시 정적 shell을 즉시 제공하고, 동적 부분은 준비되는 대로 스트림.
+
+**Next.js 16**: `cacheComponents: true` 설정 시 PPR이 App Router 기본 동작.
+`experimental.ppr` 플래그와 `experimental_ppr` 라우트 세그먼트 설정은 제거됨.
+
+---
+
+## 활성화 (Next.js 16)
+
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,  // PPR + use cache + dynamicIO 통합 활성화
+}
+
+export default nextConfig
+```
+
+---
+
+## 동작 원리
+
+```
+요청 수신
+    ↓
+정적 HTML shell → 즉시 응답 (TTFB 최소화)
+    ↓
+동적 콘텐츠 → Suspense 경계를 통해 스트리밍
+    ↓
+최종 완성된 페이지
+```
+
+---
+
+## Suspense로 정적/동적 경계 설정
+
+```tsx
+// app/page.tsx
+import { Suspense } from 'react'
+import { StaticContent } from './static-content'
+import { DynamicFeed } from './dynamic-feed'
+
+export default function Page() {
+  return (
+    <main>
+      {/* 정적 — 빌드 시 HTML에 포함 */}
+      <StaticContent />
+
+      {/* 동적 — Suspense 경계 안에서 스트리밍 */}
+      <Suspense fallback={<FeedSkeleton />}>
+        <DynamicFeed />
+      </Suspense>
+    </main>
+  )
+}
+```
+
+```tsx
+// dynamic-feed.tsx
+async function DynamicFeed() {
+  // 이 함수는 request time에 실행됨 (cookies, headers 등 사용 가능)
+  const feed = await getUserFeed()
+  return <Feed items={feed} />
+}
+```
+
+---
+
+## use cache 지시어와 함께 사용
+
+```tsx
+// cacheComponents 활성화 시 컴포넌트/함수 레벨 캐싱
+async function CachedSidebar() {
+  'use cache'
+  const nav = await getNavigation()  // 캐시됨 (정적 shell에 포함)
+  return <Sidebar items={nav} />
+}
+
+async function DynamicUserPanel() {
+  // use cache 없음 → 동적 (스트리밍)
+  const user = await getCurrentUser()
+  return <UserPanel user={user} />
+}
+```
+
+---
+
+## Activity 기반 네비게이션 (cacheComponents 활성화 시)
+
+React `<Activity>` 컴포넌트로 클라이언트 네비게이션 시 이전 라우트 상태 보존:
+- 라우트 이동 시 이전 라우트를 unmount 대신 `"hidden"` 모드로 전환
+- 뒤로 가기 시 상태 그대로 복원 (form 입력, 스크롤 위치 등)
+- `"hidden"` 상태에서 effects 정리, 복귀 시 재생성
+
+---
+
+## 이전 버전 (Next.js 13-15) experimental PPR
+
+```typescript
+// next.config.ts (Next.js 13-15)
+const nextConfig = {
+  experimental: {
+    ppr: 'incremental',  // 또는 true
+  },
+}
+
+// 라우트 세그먼트에서 opt-in
+export const experimental_ppr = true
+```
+
+---
+
+## PPR vs 기존 방식 비교
+
+| 방식 | 특징 |
+|------|------|
+| 완전 정적 (SSG) | 빌드 시 모두 생성, 개인화 불가 |
+| 완전 동적 (SSR) | 매 요청마다 렌더, TTFB 높음 |
+| **PPR** | 정적 shell 즉시 + 동적 부분 스트리밍 |
+
+PPR은 첫 HTML 응답 속도(≒ TTFB)와 개인화 동적 콘텐츠를 동시에 달성.

package/assets/dev-guide/fe/sources/perf/09-nextjs-image.md

@@ -0,0 +1,200 @@
+---
+title: Next.js Image 컴포넌트 최적화 가이드
+source: https://nextjs.org/docs/app/api-reference/components/image
+fetched: 2026-05-18
+category: images
+---
+
+## 개요
+
+`next/image`는 HTML `<img>`를 확장하여 자동 이미지 최적화를 제공한다:
+- 자동 WebP/AVIF 변환
+- 반응형 srcset 생성
+- Lazy loading 기본 적용
+- CLS 방지를 위한 크기 예약
+
+---
+
+## 기본 사용
+
+```jsx
+import Image from 'next/image'
+
+export default function Page() {
+  return (
+    <Image
+      src="/profile.png"
+      width={500}
+      height={500}
+      alt="프로필 사진"
+    />
+  )
+}
+```
+
+---
+
+## 핵심 Props 레퍼런스
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `src` | String | 필수 | 내부 경로, 외부 URL, static import |
+| `alt` | String | 필수 | 접근성 대체 텍스트 |
+| `width` | Integer(px) | - | 인트린식 너비 (aspect ratio 계산용) |
+| `height` | Integer(px) | - | 인트린식 높이 |
+| `fill` | Boolean | false | 부모 요소 크기에 맞게 채우기 |
+| `sizes` | String | - | 반응형 이미지 크기 힌트 |
+| `quality` | Integer(1-100) | 75 | 최적화 품질 |
+| `loading` | String | `'lazy'` | `'lazy'` \| `'eager'` |
+| `preload` | Boolean | false | `<link rel="preload">` 삽입 |
+| `placeholder` | String | `'empty'` | `'empty'` \| `'blur'` \| data URL |
+| `blurDataURL` | String | - | blur placeholder용 base64 이미지 |
+| `unoptimized` | Boolean | false | 최적화 비활성화 |
+| `decoding` | String | `'async'` | 이미지 디코딩 힌트 |
+
+> **주의**: `priority` prop은 Next.js 16에서 deprecated → `preload` 사용 권장
+
+---
+
+## LCP 이미지 최적화
+
+```jsx
+// 히어로 이미지 (LCP 요소) — 즉시 로딩
+<Image
+  src="/hero.webp"
+  width={1200}
+  height={600}
+  alt="히어로 이미지"
+  preload={true}      // <link rel="preload"> 삽입
+  loading="eager"     // lazy loading 비활성화
+  quality={85}
+/>
+```
+
+**언제 `preload={true}`를 쓰나:**
+- LCP 요소인 경우
+- 폴드 위(above the fold) 이미지
+- `<head>`에서 미리 로드하고 싶은 경우
+
+**쓰지 말아야 할 때:**
+- 뷰포트에 따라 LCP 요소가 달라지는 경우
+- `loading` 또는 `fetchPriority` prop과 함께 사용 시
+
+---
+
+## fill + sizes 반응형 패턴
+
+```jsx
+// fill: 부모 요소 크기에 맞게 채움
+// 부모에 position: relative/fixed/absolute 필요
+<div style={{ position: 'relative', width: '100%', height: '400px' }}>
+  <Image
+    src="/banner.jpg"
+    fill
+    alt="배너"
+    sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+    style={{ objectFit: 'cover' }}
+  />
+</div>
+```
+
+**sizes 미지정 시**: 브라우저는 이미지가 100vw라고 가정 → 불필요하게 큰 이미지 다운로드.
+
+**sizes 효과**:
+- `sizes` 없음: `1x, 2x` srcset 생성 (고정 크기)
+- `sizes` 있음: `640w, 750w, 828w, ...` 전체 srcset 생성 (반응형)
+
+---
+
+## placeholder blur 패턴
+
+```jsx
+import Image from 'next/image'
+import profilePic from './profile.jpg'  // 정적 import → blurDataURL 자동 생성
+
+export default function Profile() {
+  return (
+    <Image
+      src={profilePic}
+      alt="프로필"
+      placeholder="blur"  // 로딩 중 블러 표시
+    />
+  )
+}
+```
+
+외부 이미지의 경우 `blurDataURL` 직접 제공:
+```jsx
+<Image
+  src="https://example.com/image.jpg"
+  width={500}
+  height={500}
+  alt="외부 이미지"
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
+/>
+```
+
+---
+
+## 커스텀 loader
+
+```jsx
+'use client'
+
+import Image from 'next/image'
+
+const imageLoader = ({ src, width, quality }) => {
+  return `https://cdn.example.com/${src}?w=${width}&q=${quality || 75}`
+}
+
+export default function Page() {
+  return (
+    <Image
+      loader={imageLoader}
+      src="profile.jpg"
+      alt="프로필"
+      width={500}
+      height={500}
+    />
+  )
+}
+```
+
+---
+
+## 외부 이미지 설정 (next.config.ts)
+
+```typescript
+const nextConfig = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'cdn.example.com',
+        port: '',
+        pathname: '/images/**',
+      },
+    ],
+    // 허용 품질 값 제한
+    qualities: [75, 85, 100],
+    // 포맷 우선순위
+    formats: ['image/avif', 'image/webp'],
+  },
+}
+```
+
+---
+
+## CLS 방지 핵심
+
+`width`와 `height`는 렌더 크기가 아닌 **aspect ratio 계산**에 사용된다.
+브라우저가 이미지 로드 전 공간을 예약하여 레이아웃 이동(CLS) 방지.
+
+```jsx
+// fill 없이 사용 시 width + height 필수
+<Image src="/img.jpg" width={800} height={600} alt="..." />
+
+// fill 사용 시 width/height 불필요 (부모 크기 따라감)
+<Image src="/img.jpg" fill alt="..." />
+```