`: 동일한 지원 범위\n- IE 11은 지원하지 않음 (Picturefill 폴리필 사용 가능)\n\n### 점진적 향상\n\n```html\n\n\n \n \n```\n\n## 결론: 반응형 이미지의 미래\n\n반응형 이미지는 현대 웹 개발의 필수 요소입니다. 단순히 기술적 최적화를 넘어 사용자 경험과 접근성, 그리고 전 세계 사용자들의 경제적 부담까지 고려한 포용적 웹을 만드는 핵심 기술입니다.\n\n### 핵심 권장사항\n\n1. **자동화 우선**: 수동으로 작성하지 말고 도구를 활용하세요\n2. **단계적 구현**: 간단한 `srcset`부터 시작해서 점진적으로 고도화\n3. **성능 측정**: 실제 사용자 데이터로 개선 효과 검증\n4. **팀 차원 접근**: 디자이너, 개발자, 콘텐츠 관리자 모두 참여하는 워크플로우 구축\n\n미래의 웹은 더 빠르고, 더 접근 가능하며, 더 포용적이어야 합니다. 반응형 이미지는 그 여정의 중요한 출발점입니다.\n\n---\n\n**참고 자료**:\n- [CSS-Tricks: A Guide to the Responsive Images Syntax in HTML](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/)\n- [HTTP Archive: Web Almanac 2019 - Media](https://almanac.httparchive.org/en/2019/media)\n- [Tim Kadlec: Why we need responsive images](https://timkadlec.com/2013/06/why-we-need-responsive-images/)\n- [MDN: Responsive images](https://developer.mozilla.org/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)\n- [MDN: CSS image-set() 함수](https://developer.mozilla.org/ko/docs/Web/CSS/image/image-set)\n",
"content_text": "HTML의 srcset, sizes, picture 엘리먼트를 활용한 반응형 이미지 최적화 기법. 실무 예제와 성능 데이터로 최대 72% 용량 절약하기",
"url": "https://leeduhan.github.io/posts/css/2025-08-29-responsive-images-guide/",
"date_published": "2025-08-29T00:00:00.000Z",
"authors": [
{
"name": "지크",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"HTML",
"반응형 웹",
"성능 최적화",
"이미지 최적화",
"웹 접근성",
"srcset",
"sizes",
"picture",
"lazy loading",
"모바일 최적화",
"브라우저 호환성",
"CSS",
"JavaScript"
]
},
{
"id": "https://leeduhan.github.io/posts/react/2025-08-27-nextjs-15-navigation-caching-complete-guide/",
"title": "Next.js 15 Navigation별 캐싱 동작 완전 정리",
"content_html": "\n## 📋 목차\n\n1. [패러다임 전환: 기본 캐시에서 명시적 제어로](#패러다임-전환-기본-캐시에서-명시적-제어로)\n2. [Soft Navigation vs Hard Navigation 캐싱 차이점](#soft-navigation-vs-hard-navigation-캐싱-차이점)\n3. [Layout과 Page 컴포넌트의 캐싱 동작 분석](#layout과-page-컴포넌트의-캐싱-동작-분석)\n4. [동적 렌더링과 캐시 제어 메커니즘](#동적-렌더링과-캐시-제어-메커니즘)\n5. [App Router 캐싱 전략 심화](#app-router-캐싱-전략-심화)\n6. [fetch 동작과 재검증 전략](#fetch-동작과-재검증-전략)\n7. [실전 패턴과 마이그레이션 전략](#실전-패턴과-마이그레이션-전략)\n8. [Next.js 16과 미래 전망](#nextjs-16과-미래-전망)\n9. [프로덕션 애플리케이션을 위한 핵심 정리](#프로덕션-애플리케이션을-위한-핵심-정리)\n\n---\n\n## 패러다임 전환: 기본 캐시에서 명시적 제어로\n\nNext.js 15는 2024년 10월 21일 출시되어 애플리케이션의 캐싱 동작을 근본적으로 변경했습니다. 기존의 공격적인 기본 캐싱에서 **명시적 옵트인 제어** 방식으로 전환한 것입니다. 이는 예상치 못한 stale 데이터와 예측하기 어려운 캐시 동작에 대한 광범위한 개발자 피드백을 반영한 결정입니다.\n\n가장 중요한 변경사항은 **Router Cache**에 영향을 미칩니다: 페이지 세그먼트의 기본값이 `staleTime: 0`으로 설정되어, 클라이언트가 navigation 시 항상 새로운 데이터를 가져옵니다. 또한 `fetch` 요청과 GET Route Handler도 더 이상 기본적으로 캐시되지 않습니다.\n\n```javascript\n// Next.js 15의 기본 동작\nconst nextConfig = {\n experimental: {\n staleTimes: {\n dynamic: 0, // 동적 라우트는 캐시하지 않음 (기본값)\n static: 0, // 정적 라우트도 캐시하지 않음 (기본값)\n },\n },\n};\n\n// 이전 동작을 복원하려면 명시적으로 설정\nconst nextConfig = {\n experimental: {\n staleTimes: {\n dynamic: 30, // 30초 캐싱\n static: 300, // 5분 캐싱\n },\n },\n};\n```\n\n## Soft Navigation vs Hard Navigation 캐싱 차이점\n\n### Navigation 타입 구분법\n\nNext.js는 두 가지 서로 다른 navigation 모드를 사용하며, 각각 완전히 다른 캐싱 동작을 보입니다. **Soft navigation**은 `\n Navigation 모드: {navMode}\n
\n );\n}\n```\n\n### Navigation별 캐싱 매트릭스\n\n| Navigation 타입 | Layout | Page | 설명 |\n|-----------------|--------|------|------|\n| **Soft Navigation**\n 사용자: {userData.name} \n {children}\n
\n );\n}\n```\n\n### Page 컴포넌트의 새로운 동작\n\nNext.js 15에서 **Page 컴포넌트는 완전히 다른 동작**을 보입니다. 새로운 기본값 `staleTime: 0`으로 인해 navigation 중에 페이지가 전혀 캐시되지 않습니다.\n\n```javascript\n// /app/dashboard/page.tsx\nexport default async function DashboardPage({ \n searchParams \n}: { \n searchParams: Promise<{ tab?: string }> // Next.js 15: async\n}) {\n // searchParams도 이제 async\n const { tab } = await searchParams;\n \n console.log('Page 실행 - 매번 실행됨 (Next.js 15)');\n \n const stats = await fetch('/api/stats', {\n // Next.js 15: 명시적으로 캐시해야 함\n next: { revalidate: 60 } // 60초 캐싱\n });\n \n return (\n \n
대시보드 \n
탭: {tab}
\n
{JSON.stringify(stats, null, 2)} \n
{JSON.stringify(data)}
;\n}\n\n// 📁 app/api/users/route.ts\nexport const dynamic = 'auto';\n\nexport async function GET() {\n // API 라우트에서는 동적 함수 사용 시 자동으로 런타임에서 실행\n return Response.json({ users: [] });\n}\n```\n\n```javascript\n// 2. 'force-dynamic' - 모든 요청에 대해 새로 렌더링 (가장 많이 사용)\n// 📁 app/dashboard/layout.tsx\nexport const dynamic = 'force-dynamic';\n\nexport default async function DashboardLayout({ children }) {\n console.log('레이아웃이 매번 실행됨 - Soft Navigation에서도!');\n \n // Soft Navigation에서도 매번 서버에서 실행됨\n const userData = await fetch('/api/user', { cache: 'no-store' });\n \n return (\n \n \n {children}\n
\n );\n}\n\n// 📁 app/api/current-time/route.ts \nexport const dynamic = 'force-dynamic';\n\nexport async function GET() {\n // 매 요청마다 새로운 시간 반환 (캐시되지 않음)\n return Response.json({ \n time: new Date().toISOString(),\n random: Math.random() \n });\n}\n```\n\n```javascript\n// 3. 'error' - 정적 생성을 강제하고 동적 API 사용 시 에러 발생\n// 📁 app/about/page.tsx\nexport const dynamic = 'error';\n\nexport default async function AboutPage() {\n // ✅ 정적 데이터는 OK\n const staticData = await fetch('https://api.example.com/static', {\n cache: 'force-cache'\n });\n \n // ❌ 이런 코드가 있으면 빌드 시 에러 발생\n // const cookies = await cookies(); // Error!\n // const headers = await headers(); // Error!\n \n return (\n \n
회사 소개 \n
정적으로 생성된 페이지입니다
\n
\n
상품 목록 (정적 생성) \n
빌드 시점에 생성된 페이지
\n
\n
오류가 발생했습니다! \n
발생 시간: {errorTime}
\n
오류 내용: {error.message}
\n
다시 시도 \n
실시간 분석 데이터
;\n}\n```\n\n#### 주의사항\n\n```javascript\n// ⚠️ 컴포넌트 내부에서는 사용 불가\nfunction MyComponent() {\n // ❌ 이렇게 사용하면 안됨\n // export const dynamic = 'force-dynamic';\n \n return 컴포넌트
;\n}\n\n// ⚠️ 조건부로 설정 불가\n// ❌ 이렇게 사용하면 안됨\n// export const dynamic = process.env.NODE_ENV === 'development' ? 'force-dynamic' : 'auto';\n\n// ✅ 올바른 사용법 - 파일 최상위에서 상수로만 선언\nexport const dynamic = 'force-dynamic';\n```\n\n### connection()과 unstable_noStore()의 진화\n\nNext.js 15는 `unstable_noStore()`를 대체하는 새로운 `connection()` API를 도입했습니다.\n\n```javascript\n// 🚫 이전 방식 (deprecated)\nimport { unstable_noStore as noStore } from 'next/cache';\n\nexport default async function OldComponent() {\n noStore(); // 더 이상 권장하지 않음\n const data = await db.query(...);\n return {data}
;\n}\n\n// ✅ Next.js 15 권장 방식\nimport { connection } from 'next/server';\n\nexport default async function NewComponent() {\n await connection(); // 요청을 기다림을 명시적으로 표현\n const data = await db.query(...);\n return {data}
;\n}\n```\n\n### 비동기 요청 API들\n\n**Next.js 15의 모든 요청 의존적 API는 이제 비동기입니다**. 이는 정적 최적화를 개선하기 위해 이러한 작업의 비동기적 특성을 명시적으로 만든 것입니다.\n\n```javascript\n// Next.js 15: 모든 것이 async\nimport { cookies, headers } from 'next/headers';\n\nexport default async function MyPage({ \n params,\n searchParams \n}: { \n params: Promise<{ slug: string }>;\n searchParams: Promise<{ q?: string }>;\n}) {\n // 모든 API에 await 필요\n const cookieStore = await cookies();\n const headersList = await headers();\n const { slug } = await params;\n const { q } = await searchParams;\n \n const theme = cookieStore.get('theme');\n const userAgent = headersList.get('user-agent');\n \n return (\n \n
페이지: {slug} \n
검색어: {q}
\n
브라우저: {userAgent} \n
{/* 컴포넌트 내용 */}
;\n}\n```\n\n### 실험적 \"use cache\" 지시문과 dynamicIO\n\n```javascript\n// next.config.js에서 활성화\nconst nextConfig = {\n experimental: {\n dynamicIO: true,\n cacheComponents: true,\n },\n};\n\n// 함수 레벨에서 세밀한 캐시 제어\nexport async function getProductData(id: string) {\n 'use cache'; // 이 함수의 결과를 캐시\n const response = await fetch(`/api/products/${id}`);\n return response.json();\n}\n\n// 캐시 생명주기 설정\nimport { cacheLife } from 'next/cache';\n\nexport async function getBlogPosts() {\n 'use cache';\n cacheLife('hours'); // 또는 cacheLife({ stale: 3600, revalidate: 900, expire: 86400 })\n \n const posts = await fetch('/api/posts');\n return posts.json();\n}\n\n// 컴포넌트에서 사용\nexport default async function ProductPage({ id }: { id: string }) {\n const product = await getProductData(id); // 캐시된 함수 호출\n const posts = await getBlogPosts(); // 시간별 캐시된 함수 호출\n \n return (\n \n
{product.name} \n
\n 관련 포스트 \n {posts.map(post => (\n {post.title} \n ))}\n \n
\n
\n 시간별 데이터 \n {JSON.stringify(hourlyData, null, 2)} \n \n \n
\n 게시물 \n {posts.map(post => (\n {post.title} \n ))}\n \n
\n
{user.name} \n
{user.email}
\n
\n
로그인이 필요합니다
;\n }\n \n const user = await getUser(session.value);\n \n return (\n \n
{user.name} \n \n );\n}\n```\n\n### Suspense와 동적 컨텐츠\n\n```javascript\nimport { Suspense } from 'react';\n\n// 동적 컨텐츠를 위한 비동기 컴포넌트\nasync function DynamicUserContent() {\n await connection(); // 요청 대기\n \n const userData = await fetch('/api/user-specific-data', {\n cache: 'no-store' // 캐시하지 않음\n });\n \n return (\n \n
개인화된 컨텐츠 \n
{JSON.stringify(userData, null, 2)} \n
\n
공통 컨텐츠 \n
{commonData.message}
\n
\n {/* 캐시된 공통 컨텐츠 */}\n 사용자 데이터 로딩 중...
}>\n \n
\n 기존 데이터 \n {JSON.stringify(legacyData, null, 2)} \n \n \n
\n 새로운 캐싱 패턴 \n {JSON.stringify(newData, null, 2)} \n \n
`, `<link>`, `<meta>` 태그 자동 호이스팅\n- **향상된 오류 처리**: 단일 오류와 diff 표시, 더 나은 hydration 오류 보고\n- **ref prop 지원**: forwardRef 불필요\n- **Context provider 간소화**: Context를 provider로 직접 사용 가능\n\n## 성능 분석과 벤치마크 비교\n\n### SSR vs SSG vs ISR 성능 비교\n\n서버사이드 렌더링은 각 요청마다 MDX를 실시간으로 처리하여 복잡한 MDX 콘텐츠의 경우 요청당 **40-100ms의 처리 시간**이 소요되며, 평균적으로 **70ms 동안 Node.js 이벤트 루프를 블로킹**합니다.\n\n정적 생성은 빌드 시점에 MDX를 컴파일하여 다음과 같은 이점을 제공합니다:\n\n| 메트릭 | SSR | SSG | ISR |\n|--------|-----|-----|-----|\n| **TTFB** | 200-500ms | 100-200ms | 100-200ms* |\n| **FCP** | 800-1200ms | 300-600ms | 300-600ms* |\n| **LCP** | 1200-2000ms | 600-1200ms | 600-1200ms* |\n| **서버 부하** | 높음 | 최소 | 낮음-중간 |\n| **CDN 캐시 적중률** | 낮음 | 99%+ | 높음 |\n| **메모리 효율성** | 낮음 | 최적 | 중간 |\n\n**정적 빌드의 핵심 이점:**\n- **CDN 엣지 캐싱**: 100-200ms의 TTFB로 즉각적인 콘텐츠 전달\n- **번들 최적화**: 트리 쉐이킹과 코드 스플리팅으로 30-60% 번들 크기 감소\n- **메모리 효율성**: 런타임 메모리 사용량 최소화\n\n## 실제 구현 사례와 코드 예제\n\n### 파일 기반 라우팅과 RSC 아키텍처\n\n실제 URL `https://example.com/posts/react/2025-08-19-html2canvas_cors_guide.txt?_rsc=1ld0r` 같은 구조 분석:\n\n```javascript\n// app/posts/[category]/[slug]/page.tsx\nexport default async function PostPage({ params }) {\n const post = await getPostBySlug(params.slug)\n const { Content } = await import(`@/content/${params.slug}.mdx`)\n \n return (\n <>\n <title>{post.title} \n import('@/components/CodeBlock'))\n }} \n />\n \n \n Action Unavailable ;\n default:\n return Unknown State ;\n }\n};\n\nconst ConditionalButton = ({ buttonState }) => {\n return getActionButton(buttonState);\n};\n```\n\n### 2.2 선언적 Switch 컴포넌트 방식\n\n```tsx\n// 선언적 Switch 컴포넌트 패턴\nconst ConditionalButton = ({ buttonState }) => {\n return (\n \n \n \n \n \n \n Action Unavailable \n \n \n Unknown State \n \n \n );\n};\n```\n\n## 2. 성능 분석\n\n### 2.1 렌더링 성능 비교\n\n성능 측정 결과, Switch 문과 컴포넌트 방식 사이에 명확한 차이가 나타났습니다.\n\n| 지표 | Switch 문 | 컴포넌트 방식 | 성능 차이 |\n|------|-----------|---------------|----------|\n| **평균 렌더링 시간** | 45ms | 72ms | **60% 빠름** |\n| **메모리 사용량** | 2.1MB | 3.8MB | **45% 절약** |\n| **번들 크기** | 8.2KB | 12.7KB | **35% 작음** |\n\n### 2.2 성능 차이의 원인\n\n**Switch 문의 장점:**\n- JavaScript 엔진에서 직접 실행되어 추가 오버헤드가 없음\n- 조건에 맞는 컴포넌트만 생성하여 메모리 효율적\n- Virtual DOM 노드 수가 최소화됨\n- 트리 셰이킹 최적화에 유리함\n\n**컴포넌트 방식의 제약:**\n- 모든 Switch.Case 컴포넌트가 먼저 생성되어 메모리 사용량 증가\n- 추가 래퍼 컴포넌트로 인한 오버헤드 발생\n\n### 2.3 동적 임포트와 코드 스플리팅\n\nSwitch 문은 트리 셰이킹 최적화에도 유리합니다:\n\n```tsx\n// 트리 셰이킹에 최적화된 Switch 문 패턴\nconst getComponent = (type: ComponentType) => {\n switch (type) {\n case 'primary':\n return import('./PrimaryButton'); // 필요할 때만 로드\n case 'secondary':\n return import('./SecondaryButton');\n default:\n return import('./DefaultButton');\n }\n};\n\n// 컴포넌트 방식은 모든 Case가 잠재적으로 번들에 포함됨\n\n \n \n \n \n \n```\n\n**번들 크기 비교:**\n- Switch 문: 847KB\n- 컴포넌트 방식: 1,204KB\n- **차이:** 357KB (약 30% 증가)\n\n\n## 3. 타입 안전성과 디버깅\n\n### 3.1 TypeScript Exhaustiveness Checking\n\n**Switch 문의 타입 안전성:**\n```typescript\ntype AsyncState = \n | { status: 'idle' }\n | { status: 'loading'; progress: number }\n | { status: 'success'; data: ApiResponse }\n | { status: 'error'; message: string };\n\nfunction StatusDisplay({ state }: { state: AsyncState }) {\n switch (state.status) {\n case 'loading':\n // TypeScript가 progress 존재를 보장\n return Loading... {state.progress}%
;\n case 'success':\n // data 속성 자동 추론\n return Authentication required ;\n }\n\n return (\n \n
\n {/* 민감한 데이터는 클라이언트에서 처리 */}\n
\n
\n {post.title} \n {post.content}
\n \n )\n}\n```\n\n### generateStaticParams의 고급 활용\n\n**중첩된 동적 세그먼트와 계층적 생성:**\n\n```typescript\n// app/[category]/[product]/page.tsx\nexport async function generateStaticParams() {\n const products = await fetch('https://api.example.com/products')\n .then(res => res.json())\n \n // 인기 상품 100개만 사전 생성 - 메모리와 빌드 시간 최적화\n return products.slice(0, 100).map((product) => ({\n category: product.category.slug,\n product: product.id,\n }))\n}\n\n// 세밀한 제어 옵션\nexport const dynamicParams = false // generateStaticParams에 없는 경로는 404\nexport const dynamic = 'force-static' // 강제 정적 렌더링\nexport const revalidate = 3600 // ISR로 1시간마다 재검증\n```\n\n**대규모 데이터셋 처리 전략:**\n\n```typescript\n// 부모 레벨에서 카테고리 생성\nexport async function generateStaticParams() {\n return [\n { category: 'electronics' }, \n { category: 'clothing' }\n ]\n}\n\n// 자식 레벨에서 카테고리별 제품 생성\nexport async function generateStaticParams({ \n params: { category } \n}: { \n params: { category: string } \n}) {\n const products = await fetch(`https://api.example.com/products?category=${category}`)\n .then(res => res.json())\n return products.map((product) => ({ product: product.id }))\n}\n```\n\n### 정적 Export의 한계와 해결책\n\n정적 빌드(`output: 'export'`)의 근본적 제약은 **서버 런타임의 부재**입니다. 이는 빌드 시점에 알 수 없는 경로 처리가 불가능하며, 대규모 e-commerce 사이트에서 수천 개의 제품 페이지를 사전 생성할 때 메모리 과부하와 극도로 긴 빌드 시간을 초래합니다.\n\n**클라이언트 사이드 라우팅으로 극복:**\n\n```typescript\n// pages/[...slug].tsx - Catch-all 동적 라우트\nimport { useRouter } from 'next/router'\nimport { useEffect, useState } from 'react'\n\nexport default function DynamicPage() {\n const router = useRouter()\n const [content, setContent] = useState(null)\n \n useEffect(() => {\n if (!router.isReady) return\n \n const { slug } = router.query\n const path = Array.isArray(slug) ? slug.join('/') : slug\n \n // 경로 기반 라우팅 로직\n if (path?.startsWith('posts/')) {\n fetchPost(path.replace('posts/', '')).then(setContent)\n } else if (path?.startsWith('users/')) {\n fetchUser(path.replace('users/', '')).then(setContent)\n }\n }, [router.isReady, router.query])\n\n return {content}
\n}\n```\n\n## React 19 Server Components와 하이브리드 아키텍처\n\n### 'use server'와 'use client' 지시어 마스터하기\n\n**Server Actions의 다층적 구현:**\n\n```typescript\n// 개별 함수 레벨 Server Action\nexport default function ContactForm() {\n async function submitForm(formData: FormData) {\n 'use server' // 함수 본문 최상단\n \n const email = formData.get('email')\n const message = formData.get('message')\n \n await db.messages.create({ data: { email, message } })\n revalidatePath('/messages')\n }\n \n return (\n \n )\n}\n\n// 파일 레벨 Server Actions\n// app/actions.ts\n'use server'\n\nexport async function createUser(data: FormData) {\n const user = await db.user.create({ data })\n return user\n}\n```\n\n### React 19 Concurrent Features 통합\n\n**useTransition과 async 함수 직접 지원:**\n\n```typescript\n'use client'\nimport { useTransition, useDeferredValue } from 'react'\nimport { updateUserProfile } from '@/app/actions'\n\nfunction ProfileForm({ initialData }) {\n const [isPending, startTransition] = useTransition()\n const [searchQuery, setSearchQuery] = useState('')\n const deferredQuery = useDeferredValue(searchQuery, '') // React 19: initialValue 지원\n \n const handleSubmit = (formData: FormData) => {\n startTransition(async () => {\n // React 19: async 함수 직접 지원\n const result = await updateUserProfile(formData)\n if (result.success) {\n router.refresh()\n }\n })\n }\n \n return (\n \n )\n}\n```\n\n### 서버/클라이언트 컴포넌트 경계 최적화\n\n**Props 직렬화와 컴포넌트 전달 패턴:**\n\n```typescript\n// ✅ 직렬화 가능한 props\n\n \n\n// 최적화된 컴포넌트 경계 설정\n// app/dashboard/page.tsx - 서버 컴포넌트\nimport { getUser } from '@/lib/auth'\nimport ClientDashboard from './client-dashboard'\n\nexport default async function Dashboard() {\n const user = await getUser()\n const initialData = await fetchUserData(user.id)\n \n return (\n \n
Welcome, {user.name} \n \n {/* 정적 셸 - 빌드 시 프리렌더링 */}\n
\n \n {/* 동적 홀 - 요청 시 스트리밍 */}\n
}>\n
\n \n \n
}>\n
\n \n \n
\n
\n
}>\n
\n \n \n
\n
}>\n
\n \n \n
}>\n
\n \n \n
}>\n
\n \n
\n
{\n src: string | StaticImport;\n}\n\nexport const ProxyImage: React.FC = ({ \n src, \n ...props \n}) => {\n const isStringUrl = (src: any): src is string => typeof src === 'string';\n const isSVG = isStringUrl(src) && src.toLowerCase().includes('.svg');\n const isExternal = isStringUrl(src) && isExternalImage(src);\n \n return (\n {\n const params = new URLSearchParams({\n url: src,\n w: width.toString(),\n q: (quality || 75).toString()\n });\n return `/api/image-proxy?${params}`;\n }}\n sizes=\"(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw\"\n crossOrigin=\"anonymous\"\n {...props}\n />\n );\n};\n```\n\n### 통합 컴포넌트 패턴의 장점\n\n- ✅ **SVG 최적화**: 불필요한 최적화 없이 프록시 처리\n- ✅ **일반 이미지 최적화**: Next.js의 강력한 최적화 기능 활용\n- ✅ **CORS 완벽 해결**: 모든 외부 이미지에 대한 CORS 문제 해결\n- ✅ **캐시 효율성**: 적절한 캐싱 전략으로 성능 최적화\n- ✅ **개발자 경험**: 하나의 컴포넌트로 모든 이미지 타입 처리\n\n### API Route 프록시 사용 시 주의사항\n\n**서버 리소스 사용량 증가**:\n- Next.js Image 컴포넌트가 여러 크기별로 최적화된 이미지를 생성\n- 이 이미지들이 서버 내부 캐시에 저장됨\n- 서버 디스크 용량과 메모리 사용량 증가\n- Vercel 등 서버리스 환경에서 Function timeout 발생 가능\n\n**해결 방법**:\n- 적절한 캐시 정책 설정\n- CDN 활용으로 서버 부하 분산\n- 이미지 크기 제한 설정\n\n## 🎯 성능 최적화 및 보안 가이드\n\n### 성능 최적화 팁\n\n**1. 적극적인 브라우저 캐싱**\n```typescript\n// API Route에서 캐시 설정\nreturn new NextResponse(imageBuffer, {\n headers: {\n 'Content-Type': contentType,\n 'Cache-Control': 'public, max-age=31536000, immutable',\n 'Access-Control-Allow-Origin': '*',\n },\n});\n```\n\n**2. CDN 활용**\n- CloudFlare, AWS CloudFront로 글로벌 캐싱\n- 이미지 크기 제한 (최대 5MB)\n- 허용 도메인 화이트리스트 관리\n\n**3. 이미지 프리로딩**\n```typescript\n// 중요한 이미지 미리 로드\n {\n fallbackSrc?: string;\n}\n\nexport const ProxyImage = ({ fallbackSrc, onError, ...props }: ProxyImageProps) => {\n const [error, setError] = useState(false);\n\n const handleError = (e: React.SyntheticEvent) => {\n setError(true);\n onError?.(e);\n };\n\n // 에러 시 fallback 이미지 표시\n if (error && fallbackSrc) {\n return (\n ` 또는 ``로 변경\n2. 외부 CDN URL을 사용하는 이미지들을 우선적으로 교체\n3. 필요에 따라 `fallbackSrc` prop으로 대체 이미지 지정\n4. 기존 props(`width`, `height`, `className` 등)은 그대로 유지 가능\n\n**핵심 포인트**: ProxyImage는 Next.js Image와 동일한 API를 제공하므로, 기존 코드의 변경 없이도 CORS 문제를 해결할 수 있습니다.\n\n### 4단계: html2canvas와 함께 사용\n\nhtml2canvas로 캡처할 때 ProxyImage가 포함된 컴포넌트를 캡처하면 CORS 문제 없이 정상 작동합니다:\n\n```typescript\nimport html2canvas from 'html2canvas';\n\nconst handleCapture = async () => {\n const element = document.querySelector('[data-capture-target]') as HTMLElement;\n \n if (!element) return;\n\n try {\n const canvas = await html2canvas(element, {\n useCORS: true,\n allowTaint: false,\n scale: 2,\n backgroundColor: '#ffffff',\n });\n\n // 이미지 다운로드\n const link = document.createElement('a');\n link.download = `capture-${Date.now()}.png`;\n link.href = canvas.toDataURL('image/png');\n link.click();\n } catch (error) {\n console.error('캡처 실패:', error);\n }\n};\n```\n\n## 핵심 구현 포인트\n\n### 1. 보안 고려사항\n\n```typescript\n// 허용된 도메인만 프록시\nconst allowedDomains = [\n 'cdn.example.com',\n 'assets.mysite.com'\n];\n\nif (!allowedDomains.includes(url.hostname)) {\n return NextResponse.json({ error: 'Domain not allowed' }, { status: 403 });\n}\n```\n\n허용된 도메인만 프록시하여 보안 위험을 방지합니다.\n\n### 2. SSR 호환성\n\n```typescript\nconst isExternalImage = (src: string): boolean => {\n try {\n const url = new URL(src);\n // window.location이 아닌 프로토콜로 판단하여 SSR 안전성 확보\n return url.protocol === 'http:' || url.protocol === 'https:';\n } catch {\n return false;\n }\n};\n```\n\n서버사이드 렌더링에서도 안전하게 작동하도록 `window` 객체 의존성을 제거했습니다.\n\n### 3. 캐시 최적화\n\n```typescript\nheaders: {\n 'Content-Type': contentType,\n 'Cache-Control': 'public, max-age=31536000, immutable',\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET',\n 'Access-Control-Allow-Headers': 'Content-Type',\n}\n```\n\n이미지를 1년간 캐시하여 성능을 최적화합니다.\n\n## 트러블슈팅\n\n### 1. Hydration Mismatch 에러\n**문제**: 서버와 클라이언트에서 다른 URL 생성으로 인한 Hydration 에러 \n**해결**: `window.location.origin` 대신 프로토콜 기반으로 외부 이미지 판단\n\n### 2. 무한 로딩\n**문제**: 프록시 로더가 적용되지 않아 원본 URL로 요청 \n**해결**: SSR 안전한 로직으로 변경하여 서버/클라이언트 일관성 확보\n\n## 대안 해결 방법들\n\n### 1. 캐싱이 포함된 개선된 API Route\n\n```typescript\n// 메모리 캐시 추가\nconst imageCache = new Map();\n\nconst CACHE_DURATION = 1000 * 60 * 10; // 10분 캐시\n\nexport async function GET(request: NextRequest) {\n // 캐시 확인 로직 추가\n const cached = imageCache.get(imageUrl);\n if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {\n return new NextResponse(cached.data, {\n headers: {\n 'Content-Type': cached.contentType,\n 'Access-Control-Allow-Origin': '*',\n 'Cache-Control': 'public, max-age=300',\n },\n });\n }\n \n // fetch 후 캐시에 저장\n imageCache.set(imageUrl, {\n data: imageBuffer,\n contentType,\n timestamp: Date.now(),\n });\n}\n```\n\n### 2. 대안 라이브러리 고려\n\n```bash\nnpm install modern-screenshot\n```\n\n```typescript\nimport { domToJpeg } from 'modern-screenshot';\nconst dataUrl = await domToJpeg(element);\n```\n\n## 성능 최적화 및 추가 팁\n\n### 1. html2canvas 최적화 설정\n\n```typescript\nconst canvas = await html2canvas(element, {\n useCORS: true,\n allowTaint: false,\n scale: 2,\n logging: false,\n backgroundColor: '#ffffff',\n foreignObjectRendering: true,\n imageTimeout: 10000,\n onclone: (clonedDoc) => {\n console.log('문서 클론 완료');\n }\n});\n```\n\n### 2. 이미지 프리로딩\n\n```typescript\n// 캡처 전 이미지 프리로딩\nconst preloadImages = async (urls: string[]) => {\n await Promise.all(\n urls.map(url => \n fetch(`/api/image-proxy?url=${encodeURIComponent(url)}`, { \n cache: 'no-cache' \n })\n )\n );\n};\n```\n\n## 결과\n\n✅ **CORS 에러 해결**: 외부 CDN 이미지를 프록시를 통해 안전하게 로드 \n✅ **html2canvas 호환**: 캡처 기능이 정상적으로 작동 \n✅ **성능 최적화**: 이미지 캐싱 및 반응형 최적화 \n✅ **보안 강화**: 허용된 도메인만 프록시하여 보안 위험 방지 \n✅ **개발자 경험**: 기존 Image 컴포넌트와 동일한 API로 쉬운 사용\n\n## 마무리\n\nNext.js의 API Route를 활용한 이미지 프록시 솔루션으로 CORS 문제를 깔끔하게 해결할 수 있었습니다. 특히 SSR 호환성과 보안을 고려한 설계로 프로덕션 환경에서도 안전하게 사용할 수 있는 솔루션이 되었습니다.\n\n### 권장 구현 순서\n\n1. **1단계**: API Route 프록시 엔드포인트 생성 (10분)\n2. **2단계**: ProxyImage 컴포넌트 구현 (20분) \n3. **3단계**: 기존 이미지 컴포넌트 교체 (5분)\n4. **4단계**: html2canvas 테스트 및 최적화 (15분)\n5. **5단계**: 성능 최적화 및 캐싱 추가 (선택사항)\n\n이 순서대로 진행하면 **Next.js 15의 강력한 서버사이드 기능을 활용**하여 html2canvas CORS 문제를 **가장 효율적으로 해결**할 수 있습니다!\n\n### 핵심 성과\n\n- **html2canvas 호환성**: 외부 CDN 이미지가 포함된 화면을 성공적으로 캡처\n- **성능 최적화**: 이미지 캐싱과 반응형 최적화로 사용자 경험 향상\n- **보안 강화**: 도메인 화이트리스트로 악의적 요청 차단\n- **개발자 경험**: 기존 Image 컴포넌트와 동일한 API로 쉬운 마이그레이션\n\n이 방법은 html2canvas뿐만 아니라 Canvas API를 사용하는 다른 라이브러리(Fabric.js, Konva.js 등)에서도 동일하게 적용할 수 있어, 크로스 도메인 이미지 처리가 필요한 다양한 상황에서 유용할 것입니다.\n\n---\n\n## ⚠️ API Route 프록시 방식 주의사항\n\nAPI Route 프록시는 html2canvas CORS 문제를 해결하지만, **서버 리소스** 측면에서 고려해야 할 사항이 있습니다:\n\n### 🖼️ 서버 리소스 문제\n\n```html\n\n();\n\nconst CACHE_DURATION = 1000 * 60 * 10; // 10분 캐시\n\nexport async function GET(request: NextRequest) {\n // 캐시 확인 로직 추가\n const cached = imageCache.get(imageUrl);\n if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {\n return new NextResponse(cached.data, {\n headers: {\n 'Content-Type': cached.contentType,\n 'Access-Control-Allow-Origin': '*',\n 'Cache-Control': 'public, max-age=300',\n },\n });\n }\n \n // fetch 후 캐시에 저장\n imageCache.set(imageUrl, {\n data: imageBuffer,\n contentType,\n timestamp: Date.now(),\n });\n}\n```\n\n### 📚 더 자세한 이미지 최적화 가이드\n\nNext.js 15의 공식 권장사항과 더 자세한 성능 비교를 원한다면 **[Next.js 15 이미지 최적화 완전 가이드](/posts/react/2025-08-19-nextjs-15-image-optimization-guide)**를 참고하세요.",
"content_text": "html2canvas 사용 시 외부 CDN 이미지로 인한 CORS 에러를 Next.js API Route 프록시로 완벽 해결한 과정과 다양한 해결 방법들을 상세히 소개합니다.",
"url": "https://leeduhan.github.io/posts/react/2025-08-19-html2canvas_cors_guide/",
"date_published": "2025-08-19T00:00:00.000Z",
"authors": [
{
"name": "zeke",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"Next.js",
"html2canvas",
"CORS",
"React",
"TypeScript",
"이미지 프록시"
]
},
{
"id": "https://leeduhan.github.io/posts/react/2025-08-19-complete-guide-to-fine-grained-reactivity/",
"title": "Fine-Grained Reactivity 완벽 가이드: 차세대 반응형 프로그래밍의 모든 것",
"content_html": "\n# Fine-Grained Reactivity 완벽 가이드: 차세대 반응형 프로그래밍의 모든 것\n\n## 📑 목차\n\n### 📚 Chapter 1: Fine-Grained Reactivity의 이해\n- [1.1 핵심 개념](#11-핵심-개념-정밀한-반응성이란)\n- [1.2 Push vs Pull: 반응형 모델의 두 가지 접근](#12-push-vs-pull-반응형-모델의-두-가지-접근)\n- [1.3 FGR의 3대 핵심 원시 타입](#13-fgr의-3대-핵심-원시-타입)\n - [Signal: 반응형 값의 기본 단위](#signal-반응형-값의-기본-단위)\n - [Effect: 자동 반응형 부수 효과](#effect-자동-반응형-부수-효과)\n - [Memo: 캐싱된 파생 값](#memo-캐싱된-파생-값)\n\n### 🔧 Chapter 2: 반응형 시스템 직접 구현하기\n- [2.1 완전한 반응형 라이브러리 구축](#21-완전한-반응형-라이브러리-구축)\n- [2.2 고급 기능 추가](#22-고급-기능-추가)\n - [Batch 업데이트](#batch-업데이트)\n - [Untrack: 선택적 의존성 제외](#untrack-선택적-의존성-제외)\n - [Root: 메모리 관리](#root-메모리-관리)\n\n### ⚛️ Chapter 3: React의 리렌더링 문제와 FGR 솔루션\n- [3.1 React의 근본적인 문제](#31-react의-근본적인-문제)\n- [3.2 Legend State: React를 위한 완벽한 FGR 솔루션](#32-legend-state-react를-위한-완벽한-fgr-솔루션)\n - [📊 성능 벤치마크](#성능-벤치마크)\n - [🔧 핵심 기능 (9가지)](#핵심-기능-9가지)\n - [⚡ 성능 최적화 가이드](#성능-최적화-가이드)\n - [🏗️ 아키텍처 패턴](#아키텍처-패턴)\n- [3.3 FGR의 내부 동작 원리](#33-fgr의-내부-동작-원리)\n\n### 🚀 Chapter 4: FGR 프레임워크 총정리\n- [4.1 SolidJS: FGR의 정점](#41-solidjs-fgr의-정점)\n- [4.2 Vue 3: Composition API와 반응성](#42-vue-3-composition-api와-반응성)\n- [4.3 Svelte: 컴파일 타임 반응성](#43-svelte-컴파일-타임-반응성)\n- [4.4 MobX: 데코레이터 기반 반응성](#44-mobx-데코레이터-기반-반응성)\n- [4.5 Preact Signals: 경량 FGR 솔루션](#45-preact-signals-경량-fgr-솔루션)\n\n### 📊 Chapter 5: 실전 패턴과 최적화\n- [5.1 동적 의존성 추적 패턴](#51-동적-의존성-추적-패턴)\n- [5.2 폼 검증 시스템 구현](#52-폼-검증-시스템-구현)\n- [5.3 실시간 데이터 대시보드](#53-실시간-데이터-대시보드)\n\n### 🎯 Chapter 6: FGR vs Virtual DOM - 성능 비교\n- [6.1 벤치마크 시나리오](#61-벤치마크-시나리오)\n- [6.2 메모리 사용량 비교](#62-메모리-사용량-비교)\n\n### 🚨 Chapter 7: 주의사항과 트레이드오프\n- [7.1 FGR의 한계](#71-fgr의-한계)\n- [7.2 언제 FGR을 선택해야 하는가?](#72-언제-fgr을-선택해야-하는가)\n\n### 🎓 Chapter 8: 미래 전망\n- [8.1 React의 대응: React Forget과 Signals 제안](#81-react의-대응-react-forget과-signals-제안)\n- [8.2 웹 표준화 움직임](#82-웹-표준화-움직임)\n\n### 📝 마무리와 정리\n- [마무리와 정리](#-마무리와-정리)\n- [마지막 조언](#-마지막-조언)\n- [FGR의 미래](#-fgr의-미래)\n- [참고 자료](#-참고-자료)\n\n---\n\n## 🎯 들어가며: 웹 개발의 패러다임 전환\n\n당신이 스프레드시트에서 `=A1+B1`이라는 공식을 작성했다고 상상해보세요. A1이나 B1의 값을 변경하면, 결과가 **즉시 자동으로** 업데이트됩니다. 어떤 버튼을 클릭하거나 페이지를 새로고침할 필요가 없죠.\n\n하지만 React로 이와 같은 동작을 구현하려면 어떨까요?\n\n```tsx\n// React에서는 이렇게 해야 합니다\nfunction Calculator() {\n const [a, setA] = useState(1);\n const [b, setB] = useState(2);\n const [sum, setSum] = useState(3); // 수동으로 관리해야 함\n \n // a나 b가 변경될 때마다 수동으로 sum 업데이트\n useEffect(() => {\n setSum(a + b);\n }, [a, b]);\n \n return {sum}
; // 전체 컴포넌트 리렌더링\n}\n```\n\n**Fine-Grained Reactivity(FGR)**는 이 문제를 근본적으로 해결합니다. 스프레드시트처럼 **값이 변경되면 연관된 부분만 자동으로 업데이트**되는 시스템을 제공합니다.\n\n### 현대 웹 개발의 도전과제\n\n- **성능 병목**: 수천 개 컴포넌트의 불필요한 리렌더링\n- **복잡한 상태 관리**: 수동 의존성 추적과 메모이제이션\n- **예측 불가능한 업데이트**: 비동기 배치 처리로 인한 혼란\n- **메모리 오버헤드**: Virtual DOM의 이중 트리 구조\n\n**FGR은 이 모든 문제를 한 번에 해결합니다.**\n\n## 📚 Chapter 1: Fine-Grained Reactivity의 이해\n\n### 1.1 핵심 개념: 정밀한 반응성이란?\n\nFine-Grained Reactivity는 **상태 변경이 정확히 필요한 부분만 업데이트하는 반응형 프로그래밍 패러다임**입니다. \n\n전통적인 Virtual DOM 방식과 비교해보겠습니다:\n\n#### 🚫 Virtual DOM 방식 (React)\n1. 상태 변경 → 2. 전체 컴포넌트 함수 재실행 → 3. 새로운 Virtual DOM 생성 → 4. 이전 Virtual DOM과 비교(diff) → 5. 변경된 부분만 실제 DOM 업데이트\n\n#### ✅ Fine-Grained Reactivity 방식\n1. 상태 변경 → 2. **변경된 상태를 구독하는 특정 DOM 노드만 직접 업데이트**\n\n이제 실제 예제로 확인해보겠습니다:\n\n```typescript\n// 스프레드시트의 동작 방식\n// A1 = 10\n// B1 = 20 \n// C1 = A1 + B1 // 자동으로 30\n// A1을 15로 변경 → C1이 자동으로 35로 업데이트\n\n// FGR로 구현\nconst [a, setA] = createSignal(10);\nconst [b, setB] = createSignal(20);\nconst c = createMemo(() => a() + b());\n\nconsole.log(c()); // 30\nsetA(15);\nconsole.log(c()); // 35 (자동 업데이트!)\n```\n\n### 1.2 Push vs Pull: 반응형 모델의 두 가지 접근\n\n#### Pull 모델 (React 방식)\n```tsx\nfunction ReactComponent() {\n const [count, setCount] = useState(0);\n \n // 렌더링 시점에 값을 \"당겨옴\"\n const doubled = count * 2; // 매번 계산\n \n return {doubled}
;\n}\n```\n\n#### Push 모델 (FGR 방식)\n```tsx\nfunction FGRComponent() {\n const [count, setCount] = createSignal(0);\n const doubled = createMemo(() => count() * 2);\n \n // count 변경이 doubled로 자동으로 \"밀어냄\"\n createEffect(() => {\n console.log(\"Doubled:\", doubled());\n });\n}\n```\n\n### 1.3 FGR의 3대 핵심 원시 타입\n\n#### 🔵 Signal: 반응형 값의 기본 단위\n\nSignal은 getter와 setter를 가진 반응형 컨테이너입니다.\n\n```typescript\n// Signal의 내부 구조 (간소화)\nfunction createSignal(initialValue: T) {\n let value = initialValue;\n const subscribers = new Set<{ execute: () => void }>();\n \n const read = (): T => {\n // 현재 실행 중인 Effect가 있으면 구독자로 등록\n if (currentListener) {\n subscribers.add(currentListener);\n }\n return value;\n };\n \n const write = (newValue: T | ((prev: T) => T)): void => {\n value = typeof newValue === 'function' \n ? (newValue as (prev: T) => T)(value) \n : newValue;\n \n // 모든 구독자에게 변경 알림\n for (const sub of [...subscribers]) {\n sub.execute();\n }\n };\n \n return [read, write] as const;\n}\n```\n\n#### 🟢 Effect: 자동 반응형 부수 효과\n\nEffect는 Signal을 자동으로 추적하고 변경 시 재실행됩니다.\n\n```typescript\n// Effect의 내부 구조\nlet currentListener: { execute: () => void; dependencies: Set } | null = null;\n\nfunction createEffect(fn: () => void) {\n const execute = () => {\n // 이전 의존성 정리\n cleanup(running);\n \n // 현재 Effect를 전역 컨텍스트에 설정\n currentListener = running;\n \n try {\n fn(); // 함수 실행 중 Signal 읽기가 자동 추적됨\n } finally {\n currentListener = null;\n }\n };\n \n const running = {\n execute,\n dependencies: new Set()\n };\n \n execute(); // 초기 실행\n return running;\n}\n\nfunction cleanup(running: { dependencies: Set }) {\n for (const dep of running.dependencies) {\n dep.delete?.(running);\n }\n running.dependencies.clear();\n}\n```\n\n#### 🟡 Memo: 캐싱된 파생 값\n\nMemo는 계산 비용이 높은 파생 값을 캐싱합니다.\n\n```typescript\nfunction createMemo(fn: () => T) {\n const [signal, setSignal] = createSignal(undefined as any);\n createEffect(() => setSignal(fn()));\n return signal;\n}\n\n// 사용 예제\nconst [count, setCount] = createSignal(0);\nconst expensive = createMemo(() => {\n console.log(\"계산 중...\");\n return count() ** 2; // 제곱 계산\n});\n\nconsole.log(expensive()); // \"계산 중...\" → 0\nconsole.log(expensive()); // 0 (캐싱됨)\nsetCount(5);\nconsole.log(expensive()); // \"계산 중...\" → 25\n```\n\n## 🔧 Chapter 2: 반응형 시스템 직접 구현하기\n\n### 2.1 완전한 반응형 라이브러리 구축\n\n이제 실제로 작동하는 반응형 시스템을 처음부터 구현해봅시다.\n\n```typescript\n// reactive.ts - 완전한 구현\ntype Context = Array<{ execute: () => void; dependencies: Set }>;\nconst context: Context = [];\n\n// 양방향 구독 관계 설정\nfunction subscribe(running: { dependencies: Set }, subscriptions: Set) {\n subscriptions.add(running);\n running.dependencies.add(subscriptions);\n}\n\n// 의존성 정리\nfunction cleanup(running: { dependencies: Set }) {\n for (const dep of running.dependencies) {\n dep.delete(running);\n }\n running.dependencies.clear();\n}\n\n// Signal 구현\nexport function createSignal(value: T) {\n const subscriptions = new Set();\n\n const read = () => {\n const running = context[context.length - 1];\n if (running) subscribe(running, subscriptions);\n return value;\n };\n\n const write = (nextValue) => {\n value = typeof nextValue === 'function' \n ? nextValue(value) \n : nextValue;\n \n for (const sub of [...subscriptions]) {\n sub.execute();\n }\n };\n \n return [read, write];\n}\n\n// Effect 구현\nexport function createEffect(fn) {\n const execute = () => {\n cleanup(running);\n context.push(running);\n try {\n fn();\n } finally {\n context.pop();\n }\n };\n\n const running = {\n execute,\n dependencies: new Set()\n };\n\n execute();\n}\n\n// Memo 구현\nexport function createMemo(fn) {\n const [signal, setSignal] = createSignal();\n createEffect(() => setSignal(fn()));\n return signal;\n}\n```\n\n### 2.2 고급 기능 추가\n\n#### Batch 업데이트: 성능 최적화\n\n```javascript\nlet pending = false;\nconst queue = new Set();\n\nfunction flush() {\n if (pending) return;\n pending = true;\n \n queueMicrotask(() => {\n for (const effect of queue) {\n effect.execute();\n }\n queue.clear();\n pending = false;\n });\n}\n\nexport function batch(fn) {\n const prevQueue = queue;\n queue = new Set();\n fn();\n const effects = queue;\n queue = prevQueue;\n \n for (const effect of effects) {\n queue.add(effect);\n }\n \n if (!prevQueue.size) flush();\n}\n\n// 사용 예제\nbatch(() => {\n setFirstName(\"Jane\");\n setLastName(\"Doe\");\n}); // 한 번만 Effect 실행\n```\n\n#### Untrack: 선택적 의존성 제외\n\n```javascript\nexport function untrack(fn) {\n const prevContext = context;\n context = [];\n const result = fn();\n context = prevContext;\n return result;\n}\n\n// 사용 예제\ncreateEffect(() => {\n console.log(\"Count:\", count()); // 추적됨\n untrack(() => {\n console.log(\"Debug:\", debugInfo()); // 추적 안 됨\n });\n});\n```\n\n## ⚛️ Chapter 3: React의 리렌더링 문제와 FGR 솔루션\n\n### 3.1 React의 근본적인 문제\n\nReact의 Context API를 사용한 전역 상태 관리의 문제점을 살펴봅시다:\n\n```jsx\n// 문제가 되는 코드\nconst UserContext = createContext();\n\nfunction UserProvider({ children }) {\n const [user, setUser] = useState({\n name: \"김개발\",\n age: 25,\n theme: \"dark\",\n preferences: { /* 복잡한 중첩 객체 */ }\n });\n \n return (\n \n {children}\n \n );\n}\n\n// name만 사용하는 컴포넌트\nfunction UserName() {\n const { user } = useContext(UserContext);\n console.log(\"UserName 리렌더링!\"); // theme 변경해도 실행됨 😱\n return {user.name}
;\n}\n```\n\n### 3.2 Legend State: React를 위한 완벽한 FGR 솔루션\n\nLegend State는 가장 빠른 React 상태 관리 라이브러리로, Expo에서 공식 지원합니다. \"**성능, 간결함, 강력함**\"을 모두 갖춘 Signal 기반 상태 관리 솔루션입니다.\n\n#### 📊 성능 벤치마크\n\nLegend State는 모든 주요 React 상태 관리 라이브러리를 압도합니다:\n- **Zustand보다 5배 빠름**\n- **MobX보다 3배 빠름** \n- **Redux Toolkit보다 10배 빠름**\n- **Jotai보다 4배 빠름**\n\n#### 🔧 핵심 기능\n\n##### 1. Observable 시스템\n\n```jsx\nimport { observable } from '@legendapp/state';\n\n// 무한 중첩 가능한 Observable\nconst state$ = observable({\n user: {\n profile: {\n name: \"김개발\",\n bio: \"프론트엔드 개발자\",\n skills: [\"React\", \"TypeScript\", \"Node.js\"]\n },\n settings: {\n theme: \"dark\",\n notifications: {\n email: true,\n push: false,\n sms: false\n }\n }\n },\n todos: []\n});\n\n// 간단한 get/set 인터페이스\nconsole.log(state$.user.profile.name.get()); // \"김개발\"\nstate$.user.profile.name.set(\"박개발\");\n\n// 배열 조작\nstate$.user.profile.skills.push(\"GraphQL\");\nstate$.todos.push({ id: 1, text: \"Legend State 학습\", done: false });\n\n// 함수형 업데이트\nstate$.user.settings.theme.set(prev => prev === \"dark\" ? \"light\" : \"dark\");\n```\n\n##### 2. React 통합 - use$ 훅\n\n```jsx\nimport { observable, use$ } from '@legendapp/state';\n\nconst app$ = observable({\n count: 0,\n user: { name: \"김개발\", age: 25 },\n todos: [],\n filter: \"all\"\n});\n\nfunction SmartComponent() {\n // 필요한 부분만 정확히 구독\n const count = use$(() => app$.count.get());\n const userName = use$(() => app$.user.name.get());\n \n // 컴포넌트는 count나 user.name이 변경될 때만 리렌더링\n console.log(\"Render SmartComponent\");\n \n return (\n \n
{userName}님, 안녕하세요! \n
카운트: {count}
\n
app$.count.set(c => c + 1)}>증가 \n
\n
{app$.user.name}님 \n
나이: {app$.user.age}
\n
({\n user: null,\n todos: [],\n isLoading: false\n});\n\n// 타입 추론 완벽 지원\nconst userName = state$.user.name.get(); // string | undefined\nstate$.user.preferences.theme.set('blue'); // TS Error: 'blue'는 허용되지 않음\n\n// Observable 타입\ntype UserObservable = Observable;\n```\n\n##### 7. 고급 기능들\n\n```jsx\n// when - 조건이 충족될 때까지 대기\nimport { when } from '@legendapp/state';\n\nawait when(() => state$.user.get() !== null);\nconsole.log(\"사용자 로그인 완료!\");\n\n// observe - Observable 관찰\nimport { observe } from '@legendapp/state';\n\nconst dispose = observe(() => {\n console.log(\"Count:\", state$.count.get());\n});\n\n// onChange - 특정 Observable 변경 감지\nstate$.user.onChange((value, prev) => {\n console.log(\"User changed from\", prev, \"to\", value);\n});\n\n// batch - 여러 변경을 하나로 묶기\nimport { batch } from '@legendapp/state';\n\nbatch(() => {\n state$.user.name.set(\"새이름\");\n state$.user.age.set(30);\n state$.todos.push({ id: 1, text: \"새 할일\" });\n}); // 한 번만 리렌더링\n\n// peek - 추적 없이 값 읽기\nconst currentValue = state$.count.peek(); // Effect에서 추적되지 않음\n```\n\n##### 8. React 컴포넌트 최적화 패턴\n\n```jsx\n// Reactive 컴포넌트 - 가장 간단하고 빠른 방법\nimport { Reactive } from '@legendapp/state/react';\n\nfunction OptimizedList() {\n return (\n \n {/* 이 div는 todos가 변경될 때만 리렌더링 */}\n {state$.todos.map(todo => (\n \n todo.done.set(e.target.checked)}\n />\n {todo.text}\n \n ))}\n \n );\n}\n\n// Show/Switch 컴포넌트\nimport { Show, Switch } from '@legendapp/state/react';\n\nfunction ConditionalRender() {\n return (\n <>\n \n {(user) => \n \n \n {{\n list: () => \n \n );\n}\n\n// For 컴포넌트 - 최적화된 리스트 렌더링\nimport { For } from '@legendapp/state/react';\n\nfunction TodoList() {\n return (\n \n {(todo$, index) => (\n \n );\n}\n```\n\n##### 9. 실전 예제: 완전한 Todo 앱\n\n```jsx\nimport { observable, persistObservable, computed } from '@legendapp/state';\nimport { use$, Reactive, For, Show } from '@legendapp/state/react';\n\n// 전역 상태 정의\nconst todos$ = observable({\n items: [],\n filter: 'all',\n \n // Computed values\n filtered: () => {\n const items = todos$.items.get();\n const filter = todos$.filter.get();\n \n switch(filter) {\n case 'active': return items.filter(t => !t.done);\n case 'completed': return items.filter(t => t.done);\n default: return items;\n }\n },\n \n stats: () => {\n const items = todos$.items.get();\n return {\n total: items.length,\n active: items.filter(t => !t.done).length,\n completed: items.filter(t => t.done).length\n };\n }\n});\n\n// 영속성 설정\npersistObservable(todos$, {\n local: 'todos_app',\n pluginLocal: observablePersistLocalStorage\n});\n\n// 액션 함수들\nconst actions = {\n addTodo: (text) => {\n todos$.items.push({\n id: Date.now(),\n text,\n done: false,\n createdAt: new Date()\n });\n },\n \n toggleTodo: (id) => {\n const todo = todos$.items.find(t => t.id === id);\n if (todo) todo.done.toggle();\n },\n \n deleteTodo: (id) => {\n todos$.items.set(prev => prev.filter(t => t.id !== id));\n },\n \n clearCompleted: () => {\n todos$.items.set(prev => prev.filter(t => !t.done));\n }\n};\n\n// React 컴포넌트\nfunction TodoApp() {\n const stats = use$(todos$.stats);\n \n return (\n \n
Todo App with Legend State \n \n
\n \n
\n 필터: {todos$.filter}\n todos$.filter.set('all')}>전체 \n todos$.filter.set('active')}>진행중 \n todos$.filter.set('completed')}>완료 \n \n \n
\n {(todo$) => \n \n
\n 전체: {stats.total} | \n 진행중: {stats.active} | \n 완료: {stats.completed}\n
\n
\n {todos.map(todo => (\n
\n );\n}\n\n// ✅ Good: For 컴포넌트로 최적화\nimport { For } from '@legendapp/state/react';\n\nfunction TodoListOptimized() {\n return (\n \n \n {(todo$) => \n
\n );\n}\n\n// 고급: 아이템별 메모이제이션\nconst TodoItem = memo(({ todo$ }) => {\n const todo = use$(todo$);\n return (\n \n {todo$.text} \n todo$.done.set(e.target.checked)}\n />\n
\n );\n});\n```\n\n##### 4. ID 기반 안정적인 참조\n\n```javascript\n// ✅ 객체 배열에는 항상 고유 ID 사용\nconst todos$ = observable([\n { id: 1, text: \"Learn Legend State\", done: false },\n { id: 2, text: \"Build awesome app\", done: false }\n]);\n\n// ID를 통한 안정적인 Observable 참조\nfunction TodoApp() {\n const addTodo = (text) => {\n todos$.push({\n id: Date.now(), // 고유 ID 생성\n text,\n done: false\n });\n };\n \n const updateTodo = (id, updates) => {\n // ID로 특정 아이템 찾아 업데이트\n const todo = todos$.find(t => t.id.peek() === id);\n if (todo) {\n Object.assign(todo, updates);\n }\n };\n \n return (\n \n {(todo$, index) => (\n // 안정적인 key로 React 최적화\n \n );\n}\n```\n\n##### 5. 선택적 추적과 peek() 활용\n\n```javascript\n// peek()을 사용한 조건부 렌더링 최적화\nfunction SmartComponent() {\n const isDebugMode = state$.debug.peek(); // 추적하지 않음\n \n // debug 모드 변경 시 리렌더링되지 않음\n if (isDebugMode) {\n console.log('Debug info:', state$.data.peek());\n }\n \n // 실제로 추적이 필요한 값만 get() 사용\n const importantData = use$(state$.importantData);\n \n return {importantData}
;\n}\n\n// 계산 최적화\nconst expensiveCalculation = createMemo(() => {\n const config = state$.config.peek(); // 설정은 추적 안 함\n const data = state$.data.get(); // 데이터만 추적\n \n return processData(data, config);\n});\n```\n\n#### 🏗️ Legend State 아키텍처 패턴\n\n##### 1. 글로벌 상태 패턴 (Centralized)\n\n```typescript\n// stores/globalState.ts\nimport { observable } from '@legendapp/state';\n\n// 전체 앱 상태를 하나의 Observable로 관리\nexport const globalState$ = observable({\n // 인증 관련\n auth: {\n user: null as User | null,\n token: null as string | null,\n isAuthenticated: false\n },\n \n // UI 상태\n ui: {\n theme: 'light' as 'light' | 'dark',\n sidebarOpen: true,\n modals: {\n settings: false,\n profile: false\n },\n notifications: [] as Notification[]\n },\n \n // 비즈니스 데이터\n data: {\n products: [] as Product[],\n orders: [] as Order[],\n customers: [] as Customer[]\n },\n \n // 설정\n settings: {\n language: 'ko',\n timezone: 'Asia/Seoul',\n notifications: {\n email: true,\n push: false\n }\n }\n});\n\n// Computed values\nexport const computed$ = observable({\n // 파생 상태들\n activeOrders: () => {\n return globalState$.data.orders.get()\n .filter(order => order.status === 'active');\n },\n \n totalRevenue: () => {\n return globalState$.data.orders.get()\n .reduce((sum, order) => sum + order.total, 0);\n },\n \n userDisplayName: () => {\n const user = globalState$.auth.user.get();\n return user ? `${user.firstName} ${user.lastName}` : 'Guest';\n }\n});\n\n// Actions\nexport const actions = {\n login: async (credentials: LoginCredentials) => {\n const response = await api.login(credentials);\n batch(() => {\n globalState$.auth.user.set(response.user);\n globalState$.auth.token.set(response.token);\n globalState$.auth.isAuthenticated.set(true);\n });\n },\n \n logout: () => {\n batch(() => {\n globalState$.auth.set({\n user: null,\n token: null,\n isAuthenticated: false\n });\n });\n },\n \n toggleTheme: () => {\n globalState$.ui.theme.set(prev => \n prev === 'light' ? 'dark' : 'light'\n );\n }\n};\n```\n\n##### 2. 모듈식 Atom 패턴 (Decentralized)\n\n```typescript\n// stores/atoms/authAtom.ts\nexport const auth$ = observable({\n user: null as User | null,\n token: null as string | null,\n \n // Atom 내부 computed\n isAuthenticated: () => auth$.user.get() !== null,\n \n // Atom 내부 actions\n login: async (credentials: LoginCredentials) => {\n const response = await api.login(credentials);\n batch(() => {\n auth$.user.set(response.user);\n auth$.token.set(response.token);\n });\n },\n \n logout: () => {\n auth$.user.set(null);\n auth$.token.set(null);\n }\n});\n\n// stores/atoms/uiAtom.ts\nexport const ui$ = observable({\n theme: 'light' as Theme,\n sidebarOpen: true,\n \n toggleTheme: () => {\n ui$.theme.set(prev => prev === 'light' ? 'dark' : 'light');\n },\n \n toggleSidebar: () => {\n ui$.sidebarOpen.set(prev => !prev);\n }\n});\n\n// stores/atoms/productsAtom.ts\nexport const products$ = observable({\n items: [] as Product[],\n loading: false,\n error: null as string | null,\n \n // 파생 상태\n featured: () => products$.items.get().filter(p => p.featured),\n \n inStock: () => products$.items.get().filter(p => p.stock > 0),\n \n // Actions\n fetch: async () => {\n products$.loading.set(true);\n try {\n const data = await api.getProducts();\n products$.items.set(data);\n } catch (error) {\n products$.error.set(error.message);\n } finally {\n products$.loading.set(false);\n }\n }\n});\n```\n\n##### 3. 컴포넌트 레벨 상태 패턴\n\n```typescript\n// hooks/useComponentState.ts\nimport { useObservable } from '@legendapp/state/react';\n\n// 재사용 가능한 커스텀 훅\nexport function useFormState(initialValues: T) {\n const form$ = useObservable({\n values: initialValues,\n errors: {} as Record,\n touched: {} as Record,\n isSubmitting: false,\n \n // Computed\n isValid: () => {\n const errors = form$.errors.get();\n return Object.keys(errors).length === 0;\n },\n \n // Actions\n setField: (field: keyof T, value: any) => {\n form$.values[field].set(value);\n form$.touched[field].set(true);\n },\n \n setError: (field: keyof T, error: string) => {\n form$.errors[field].set(error);\n },\n \n reset: () => {\n batch(() => {\n form$.values.set(initialValues);\n form$.errors.set({});\n form$.touched.set({});\n form$.isSubmitting.set(false);\n });\n },\n \n submit: async (onSubmit: (values: T) => Promise) => {\n form$.isSubmitting.set(true);\n try {\n await onSubmit(form$.values.get());\n form$.reset();\n } finally {\n form$.isSubmitting.set(false);\n }\n }\n });\n \n return form$;\n}\n\n// 컴포넌트에서 사용\nfunction LoginForm() {\n const form$ = useFormState({\n email: '',\n password: ''\n });\n \n const handleSubmit = () => {\n form$.submit(async (values) => {\n await auth$.login(values);\n });\n };\n \n return (\n \n );\n}\n```\n\n##### 4. Context와 Provider 패턴\n\n```typescript\n// contexts/AppStateContext.tsx\nimport { createContext, useContext } from 'react';\nimport { Observable } from '@legendapp/state';\n\ninterface AppState {\n user: User | null;\n settings: Settings;\n // ...\n}\n\nconst AppStateContext = createContext | null>(null);\n\nexport function AppStateProvider({ children }) {\n const state$ = useObservable({\n user: null,\n settings: defaultSettings\n });\n \n // 영속성 설정\n useEffect(() => {\n persistObservable(state$.settings, {\n local: 'app_settings'\n });\n }, []);\n \n return (\n \n {children}\n \n );\n}\n\nexport function useAppState() {\n const state$ = useContext(AppStateContext);\n if (!state$) {\n throw new Error('useAppState must be used within AppStateProvider');\n }\n return state$;\n}\n\n// 사용\nfunction SomeComponent() {\n const state$ = useAppState();\n const user = use$(state$.user);\n \n return Welcome, {user?.name}!
;\n}\n```\n\n##### 5. 도메인 기반 아키텍처\n\n```typescript\n// domains/shopping/state.ts\nclass ShoppingDomain {\n private state$ = observable({\n cart: {\n items: [] as CartItem[],\n coupon: null as string | null\n },\n \n checkout: {\n step: 'cart' as CheckoutStep,\n shippingAddress: null as Address | null,\n paymentMethod: null as PaymentMethod | null\n }\n });\n \n // Getters\n get cart$() { return this.state$.cart; }\n get checkout$() { return this.state$.checkout; }\n \n // Computed\n readonly total$ = observable(() => {\n const items = this.cart$.items.get();\n const subtotal = items.reduce((sum, item) => \n sum + (item.price * item.quantity), 0\n );\n \n const coupon = this.cart$.coupon.get();\n const discount = coupon ? calculateDiscount(subtotal, coupon) : 0;\n \n return {\n subtotal,\n discount,\n total: subtotal - discount\n };\n });\n \n // Actions\n addToCart(product: Product, quantity = 1) {\n const existingItem = this.cart$.items.find(\n item => item.productId.peek() === product.id\n );\n \n if (existingItem) {\n existingItem.quantity.set(prev => prev + quantity);\n } else {\n this.cart$.items.push({\n productId: product.id,\n name: product.name,\n price: product.price,\n quantity\n });\n }\n }\n \n removeFromCart(productId: string) {\n this.cart$.items.set(prev => \n prev.filter(item => item.productId !== productId)\n );\n }\n \n applyCoupon(code: string) {\n // 쿠폰 검증 로직\n this.cart$.coupon.set(code);\n }\n \n proceedToCheckout() {\n if (this.cart$.items.get().length === 0) {\n throw new Error('Cart is empty');\n }\n this.checkout$.step.set('shipping');\n }\n}\n\nexport const shoppingDomain = new ShoppingDomain();\n```\n\nLegend State는 \"**Write Less, Do More**\" 철학으로 복잡한 상태 관리를 단순하게 만들어줍니다.\n\n### 3.3 FGR의 내부 동작 원리\n\n```javascript\n// Observable의 핵심 구조\nconst observableValue = {\n _value: \"초기값\",\n _handlers: [], // 구독자들\n \n get() {\n // 현재 실행 중인 Effect를 구독자로 등록\n if (currentTracker) {\n this._handlers.push(currentTracker);\n }\n return this._value;\n },\n \n set(newValue) {\n this._value = newValue;\n // 구독자들에게 알림\n this._handlers.forEach(handler => handler());\n }\n};\n\n// use$ 훅의 간소화된 구현\nfunction use$(callback) {\n const [, forceUpdate] = useReducer(x => x + 1, 0);\n \n useEffect(() => {\n effect(() => {\n callback(); // Observable 값 읽기 (자동 구독)\n forceUpdate(); // 값 변경 시 리렌더링\n });\n }, []);\n \n return callback();\n}\n```\n\n## 🚀 Chapter 4: FGR 프레임워크 총정리\n\n### 4.1 SolidJS: FGR의 정점\n\nSolidJS는 FGR을 핵심으로 설계된 프레임워크입니다.\n\n```jsx\nimport { createSignal, createEffect, createMemo, Show, For } from 'solid-js';\n\nfunction TodoApp() {\n const [todos, setTodos] = createSignal([]);\n const [filter, setFilter] = createSignal('all');\n \n // 자동 메모이제이션\n const filteredTodos = createMemo(() => {\n const currentFilter = filter();\n const currentTodos = todos();\n \n switch(currentFilter) {\n case 'active': return currentTodos.filter(t => !t.done);\n case 'completed': return currentTodos.filter(t => t.done);\n default: return currentTodos;\n }\n });\n \n const stats = createMemo(() => ({\n total: todos().length,\n active: todos().filter(t => !t.done).length,\n completed: todos().filter(t => t.done).length\n }));\n \n // JSX는 한 번만 실행됨\n return (\n \n
전체: {stats().total}
\n
\n {(todo) => \n
count++}>\n {count} × 2 = {doubled}\n \n```\n\n### 4.4 MobX: 데코레이터 기반 반응성\n\n```javascript\nimport { makeObservable, observable, computed, autorun, action } from 'mobx';\n\nclass TodoStore {\n todos = [];\n filter = \"all\";\n \n constructor() {\n makeObservable(this, {\n todos: observable,\n filter: observable,\n filteredTodos: computed,\n addTodo: action\n });\n }\n \n get filteredTodos() {\n switch(this.filter) {\n case \"active\": return this.todos.filter(t => !t.done);\n case \"completed\": return this.todos.filter(t => t.done);\n default: return this.todos;\n }\n }\n \n addTodo(text) {\n this.todos.push({ text, done: false });\n }\n}\n\nconst store = new TodoStore();\n\n// 자동 반응\nautorun(() => {\n console.log(`Todos: ${store.filteredTodos.length}`);\n});\n```\n\n### 4.5 Preact Signals: 경량 FGR 솔루션\n\nPreact는 2022년 Signals를 도입하여 선택적 FGR을 지원합니다.\n\n```jsx\nimport { signal, computed, effect } from '@preact/signals';\n\n// 컴포넌트 외부에서도 정의 가능\nconst globalCount = signal(0);\nconst doubled = computed(() => globalCount.value * 2);\n\nfunction Counter() {\n // 컴포넌트는 한 번만 렌더링\n console.log(\"Component rendered once\");\n \n return (\n \n {globalCount} {/* 텍스트 노드만 업데이트 */}\n {doubled} \n globalCount.value++}>+ \n
\n );\n}\n\n// 컴포넌트 외부에서 Effect\neffect(() => {\n document.title = `Count: ${globalCount.value}`;\n});\n```\n\n## 📊 Chapter 5: 실전 패턴과 최적화\n\n### 5.1 동적 의존성 추적 패턴\n\n```javascript\nconst [showDetails, setShowDetails] = createSignal(false);\nconst [summary, setSummary] = createSignal(\"요약\");\nconst [details, setDetails] = createSignal(\"상세 정보\");\n\ncreateEffect(() => {\n console.log(\"Summary:\", summary());\n \n // 조건부 의존성\n if (showDetails()) {\n console.log(\"Details:\", details());\n }\n});\n\n// showDetails가 false일 때\nsetDetails(\"새 상세 정보\"); // Effect 실행 안 됨!\nsetShowDetails(true); // 이제 details도 추적 시작\n```\n\n### 5.2 폼 검증 시스템 구현\n\n```javascript\nfunction createFormValidator() {\n const fields = {\n email: createSignal(\"\"),\n password: createSignal(\"\"),\n confirmPassword: createSignal(\"\")\n };\n \n const validators = {\n email: createMemo(() => {\n const value = fields.email[0]();\n if (!value) return { valid: false, error: \"필수 입력\" };\n if (!value.includes('@')) return { valid: false, error: \"올바른 이메일 형식이 아닙니다\" };\n return { valid: true };\n }),\n \n password: createMemo(() => {\n const value = fields.password[0]();\n if (value.length < 8) return { valid: false, error: \"8자 이상 입력\" };\n if (!/[A-Z]/.test(value)) return { valid: false, error: \"대문자 포함 필수\" };\n if (!/[0-9]/.test(value)) return { valid: false, error: \"숫자 포함 필수\" };\n return { valid: true };\n }),\n \n confirmPassword: createMemo(() => {\n const password = fields.password[0]();\n const confirm = fields.confirmPassword[0]();\n if (password !== confirm) return { valid: false, error: \"비밀번호가 일치하지 않습니다\" };\n return { valid: true };\n })\n };\n \n const isFormValid = createMemo(() => {\n return Object.values(validators).every(v => v().valid);\n });\n \n const errors = createMemo(() => {\n return Object.entries(validators)\n .filter(([_, validator]) => !validator().valid)\n .map(([field, validator]) => ({\n field,\n error: validator().error\n }));\n });\n \n return { fields, validators, isFormValid, errors };\n}\n```\n\n### 5.3 실시간 데이터 대시보드\n\n```javascript\nfunction createRealtimeDashboard() {\n const [data, setData] = createSignal([]);\n const [filters, setFilters] = createStore({\n status: \"all\",\n dateRange: { start: null, end: null },\n searchTerm: \"\"\n });\n \n // 다단계 파생 상태\n const filtered = createMemo(() => {\n let result = data();\n \n if (filters.status !== \"all\") {\n result = result.filter(item => item.status === filters.status);\n }\n \n if (filters.searchTerm) {\n result = result.filter(item => \n item.name.toLowerCase().includes(filters.searchTerm.toLowerCase())\n );\n }\n \n if (filters.dateRange.start && filters.dateRange.end) {\n result = result.filter(item => \n item.date >= filters.dateRange.start && \n item.date <= filters.dateRange.end\n );\n }\n \n return result;\n });\n \n const sorted = createMemo(() => {\n return [...filtered()].sort((a, b) => b.date - a.date);\n });\n \n const stats = createMemo(() => ({\n total: filtered().length,\n active: filtered().filter(i => i.status === \"active\").length,\n pending: filtered().filter(i => i.status === \"pending\").length,\n completed: filtered().filter(i => i.status === \"completed\").length,\n avgValue: filtered().reduce((sum, i) => sum + i.value, 0) / filtered().length || 0\n }));\n \n const chartData = createMemo(() => {\n const grouped = filtered().reduce((acc, item) => {\n const date = item.date.toDateString();\n acc[date] = (acc[date] || 0) + item.value;\n return acc;\n }, {});\n \n return Object.entries(grouped).map(([date, value]) => ({ date, value }));\n });\n \n // WebSocket 연결 시뮬레이션\n createEffect(() => {\n const ws = new WebSocket('ws://localhost:8080');\n \n ws.onmessage = (event) => {\n const newItem = JSON.parse(event.data);\n setData(prev => [...prev, newItem]);\n };\n \n return () => ws.close();\n });\n \n return { sorted, stats, chartData, filters, setFilters };\n}\n```\n\n## 🎯 Chapter 6: FGR vs Virtual DOM - 성능 비교\n\n### 6.1 벤치마크 시나리오\n\n```javascript\n// 1000개의 아이템을 가진 리스트에서 하나의 아이템 업데이트\n\n// React (Virtual DOM)\nfunction ReactList({ items }) {\n return (\n \n {items.map(item => (\n \n {item.name}: {item.value}\n \n ))}\n \n );\n}\n// 결과: 전체 리스트 Virtual DOM 재생성 → 비교 → 하나의 DOM 노드 업데이트\n\n// SolidJS (FGR)\nfunction SolidList(props) {\n return (\n \n \n {(item) => (\n \n {item.name}: {item.value}\n \n )}\n \n \n );\n}\n// 결과: 변경된 아이템의 텍스트 노드만 직접 업데이트\n```\n\n### 6.2 메모리 사용량 비교\n\n```javascript\n// Virtual DOM 방식\n// - 전체 컴포넌트 트리의 Virtual DOM 객체 유지\n// - 이전 Virtual DOM과 새 Virtual DOM 두 개 보관\n// - Fiber 노드 추가 메모리\n\n// FGR 방식 \n// - Signal-Effect 연결 그래프만 유지\n// - Virtual DOM 없음\n// - 컴포넌트 인스턴스 최소화\n```\n\n## 🚨 Chapter 7: 주의사항과 트레이드오프\n\n### 7.1 FGR의 한계\n\n```javascript\n// 1. 학습 곡선\n// React 개발자가 익숙한 패턴\nconst [state, setState] = useState({ name: \"김개발\", age: 25 });\nsetState({ ...state, age: 26 });\n\n// FGR에서 요구되는 패턴\nconst state = createStore({ name: \"김개발\", age: 25 });\nsetState(\"age\", 26);\n\n// 2. 디버깅의 복잡성\n// 반응형 그래프가 복잡해지면 의존성 추적이 어려움\ncreateEffect(() => {\n // 이 Effect가 왜 실행되었는지 추적하기 어려울 수 있음\n const result = complexCalculation();\n sideEffect(result);\n});\n\n// 3. 생태계 호환성\n// React 생태계의 라이브러리들과 호환성 문제\n// - React DevTools 지원 제한\n// - 써드파티 컴포넌트 라이브러리 통합 어려움\n```\n\n### 7.2 언제 FGR을 선택해야 하는가?\n\n✅ **FGR이 적합한 경우:**\n- 실시간 데이터가 많은 대시보드\n- 복잡한 상태 의존성을 가진 애플리케이션\n- 성능이 매우 중요한 모바일 웹\n- 세밀한 반응성 제어가 필요한 경우\n\n❌ **FGR이 부적합한 경우:**\n- 간단한 CRUD 애플리케이션\n- SEO가 중요한 콘텐츠 사이트\n- React 생태계에 깊게 의존하는 프로젝트\n- 팀의 학습 비용이 부담되는 경우\n\n## 🎓 Chapter 8: 미래 전망\n\n### 8.1 React의 대응: React Forget과 Signals 제안\n\n```javascript\n// React Forget (자동 메모이제이션 컴파일러)\nfunction Component({ data }) {\n // 컴파일러가 자동으로 useMemo 적용\n const expensive = data.map(item => heavyComputation(item));\n return
;\n}\n\n// React Signals 제안 (TC39 Stage 1)\nconst counter = new Signal(0);\nconst doubled = new Computed(() => counter.value * 2);\n\neffect(() => {\n console.log(doubled.value);\n});\n```\n\n### 8.2 웹 표준화 움직임\n\nJavaScript 표준에 Signals를 추가하려는 TC39 제안이 진행 중입니다. 이것이 실현되면:\n\n- 프레임워크 간 상호 운용성 향상\n- 브라우저 수준의 최적화 가능\n- 표준화된 반응형 프로그래밍 모델\n\n## 📝 마무리: FGR로 시작하는 새로운 개발 경험\n\nFine-Grained Reactivity는 단순히 성능 최적화 기법이 아닙니다. **개발자 경험과 사용자 경험을 동시에 혁신하는 패러다임 전환**입니다.\n\n### 🎯 FGR이 가져다주는 변화\n\n| 측면 | 기존 방식 | FGR 방식 | 개선 효과 |\n|------|----------|----------|----------|\n| **성능** | 전체 컴포넌트 리렌더링 | 변경 부분만 업데이트 | 5-10배 빠른 업데이트 |\n| **메모리** | Virtual DOM 이중 구조 | 직접 DOM 조작 | 50% 메모리 절약 |\n| **개발 경험** | 수동 의존성 관리 | 자동 추적 | 버그 90% 감소 |\n| **코드 복잡도** | useEffect, useMemo 남발 | 선언적 파생 상태 | 코드량 30% 감소 |\n\n\n### 🚀 지금 시작하는 FGR 로드맵\n\n#### 1단계: 개념 학습 (1주)\n```typescript\n// 간단한 카운터로 Signal 패턴 익히기\nconst [count, setCount] = createSignal(0);\nconst doubled = createMemo(() => count() * 2);\n\ncreateEffect(() => {\n console.log(`Count: ${count()}, Doubled: ${doubled()}`);\n});\n```\n\n#### 2단계: 부분 적용 (2-4주)\n- **React 프로젝트**: Legend State로 전역 상태 관리\n- **새 프로젝트**: SolidJS로 간단한 페이지 구현\n- **Vue 사용자**: Composition API의 reactive/computed 적극 활용\n\n#### 3단계: 프로덕션 준비 (2-3개월)\n- 팀 교육 및 코딩 컨벤션 수립\n- 기존 프로젝트 점진적 마이그레이션\n- 성능 모니터링 및 최적화\n\n### 🎓 마지막 조언\n\n**\"완벽한 기술은 없지만, 더 나은 선택은 있습니다.\"**\n\nFGR은 다음과 같은 프로젝트에 특히 적합합니다:\n- ✅ 실시간 데이터 처리가 중요한 대시보드\n- ✅ 복잡한 상태 의존성을 가진 애플리케이션 \n- ✅ 모바일 성능이 중요한 PWA\n- ✅ 새로 시작하는 프로젝트\n\n반면 다음의 경우는 신중하게 고려하세요:\n- ⚠️ 단순한 콘텐츠 중심 웹사이트\n- ⚠️ React 생태계에 깊게 의존하는 레거시 프로젝트\n- ⚠️ 팀의 학습 리소스가 제한적인 상황\n\n### 🌟 FGR의 미래\n\nTC39에서 JavaScript 표준으로 Signals 제안이 진행 중이며, React도 React Forget과 Signals 도입을 검토하고 있습니다. **FGR은 선택이 아닌 필수가 되어가고 있습니다.**\n\n지금 시작하면, 당신은 **웹 개발의 다음 10년을 준비하는 것**입니다.\n\n---\n\n## 📚 참고 자료\n\n### 공식 문서\n- [SolidJS Documentation](https://docs.solidjs.com)\n- [Vue 3 Reactivity](https://vuejs.org/guide/extras/reactivity-in-depth.html)\n- [Legend State](https://legendapp.com/open-source/state/)\n- [Preact Signals](https://preactjs.com/guide/v10/signals/)\n\n### 심화 학습\n- [Building a Reactive Library from Scratch](https://dev.to/ryansolid/building-a-reactive-library-from-scratch-1i0p)\n- [A Hands-on Introduction to Fine-Grained Reactivity](https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf)\n- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)\n\n### 커뮤니티\n- [SolidJS Discord](https://discord.com/invite/solidjs)\n- [Vue.js Discord](https://discord.com/invite/vue)\n- [Svelte Discord](https://discord.com/invite/svelte)\n",
"content_text": "Virtual DOM의 한계를 넘어선 Fine-Grained Reactivity의 핵심 개념부터 실전 구현까지. SolidJS, Vue 3, Legend State 등 주요 FGR 프레임워크와 성능 최적화 기법을 상세히 다룹니다.",
"url": "https://leeduhan.github.io/posts/react/2025-08-19-complete-guide-to-fine-grained-reactivity/",
"date_published": "2025-08-19T00:00:00.000Z",
"authors": [
{
"name": "김개발",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"Fine Grained Reactivity",
"FGR",
"React",
"SolidJS",
"Vue3",
"Legend State",
"Signal",
"Effect",
"Memo",
"상태관리",
"성능최적화",
"반응형 시스템"
]
},
{
"id": "https://leeduhan.github.io/posts/css/html-data-attributes-guide/",
"title": "HTML 데이터 속성(Data Attributes) 완전 가이드",
"content_html": "\n# HTML 데이터 속성(Data Attributes) 가이드\n\n웹 개발을 하다 보면 HTML 요소에 추가적인 정보를 저장해야 할 때가 자주 있습니다. 예를 들어 버튼을 클릭했을 때 어떤 동작을 할지, 특정 요소의 상태 정보는 무엇인지 같은 정보들을 말입니다.\n\n이런 상황에서 매우 유용한 것이 바로 **HTML 데이터 속성(Data Attributes)**입니다. 이번 글에서는 데이터 속성의 개념부터 실제 활용 방법까지 상세하게 알아보겠습니다.\n\n## 목차\n\n1. [데이터 속성이란 무엇인가?](#데이터-속성이란-무엇인가)\n2. [데이터 속성을 사용하는 이유](#데이터-속성을-사용하는-이유)\n3. [데이터 속성 기본 문법](#데이터-속성-기본-문법)\n4. [HTML에서 데이터 속성 사용하기](#html에서-데이터-속성-사용하기)\n5. [CSS로 데이터 속성 활용하기](#css로-데이터-속성-활용하기)\n6. [JavaScript로 데이터 속성 다루기](#javascript로-데이터-속성-다루기)\n7. [실무에서 바로 쓸 수 있는 예제들](#실무에서-바로-쓸-수-있는-예제들)\n8. [알아두면 좋은 주의사항들](#알아두면-좋은-주의사항들)\n\n---\n\n## 데이터 속성이란 무엇인가?\n\n데이터 속성(Data Attributes)은 HTML 요소에 사용자 정의 정보를 저장할 수 있게 해주는 특별한 속성입니다.\n\n이를 쉽게 비유하면, HTML 요소마다 작은 메모장을 하나씩 달아주는 것과 같습니다. 이 메모장에는 해당 요소와 관련된 다양한 정보를 저장할 수 있습니다.\n\n### 데이터 속성의 주요 특징\n\n- 모든 데이터 속성은 반드시 `data-`로 시작해야 합니다\n- HTML 표준을 완전히 준수하면서도 사용자 정의 정보를 저장할 수 있습니다\n- 화면에는 직접 표시되지 않지만, CSS와 JavaScript에서 활용할 수 있습니다\n- 모든 최신 브라우저에서 지원되므로 안정적으로 사용할 수 있습니다\n\n## 데이터 속성을 사용하는 이유\n\n데이터 속성의 유용성을 이해하기 위해 간단한 예를 살펴보겠습니다. 학교 홈페이지에서 학생 목록을 만드는 상황을 가정해보겠습니다:\n\n```html\n\n김철수
\n\n\n김철수
\n```\n\n위 예제에서 볼 수 있듯이, 데이터 속성을 사용하면 학년, 반, 번호 같은 추가 정보를 HTML에 체계적으로 저장할 수 있습니다. 이러한 정보들은 나중에 JavaScript로 학생을 검색하거나 필터링할 때 매우 유용하게 활용됩니다.\n\n## 데이터 속성 기본 문법\n\n데이터 속성을 올바르게 사용하려면 몇 가지 간단한 규칙만 알면 됩니다.\n\n### 속성 이름 작성 규칙\n\n```html\n\n
\n
\n
\n
\n\n\n
\n\n
\n\n
\n\n```\n\n**주요 규칙:**\n\n- `data-` 뒤에는 반드시 의미 있는 이름을 작성해야 합니다\n- 이름은 소문자와 하이픈(-)을 사용하는 것이 좋습니다\n- 여러 단어를 연결할 때는 `data-user-name`처럼 하이픈을 사용합니다\n\n### 값 없는 데이터 속성\n\n```html\n\n
\n\n
\n\n
\n\n```\n\n## HTML에서 데이터 속성 사용하기\n\n이제 실제 프로젝트에서 데이터 속성을 어떻게 활용하는지 구체적인 예제를 통해 살펴보겠습니다.\n\n### 실제 예제 1: 레벨바\n\n다음은 시스템 리소스 사용량을 표시하는 레벨바 예제입니다:\n\n```html\n\n\n \n 시스템 레벨바 예제 \n \n \n \n \n
\n \n CPU \n \n \n \n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n \n MEM \n \n \n \n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n \n DISK \n \n \n \n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n \n
Aspect Ratio 예제 \n \n \n \n \n \n
16:9 비율 컨테이너 (와이드스크린)
\n
\n
4:3 비율 컨테이너 (클래식 비율)
\n
\n
1:1 정사각형 (인스타그램 스타일)
\n
카운터 예제 \n \n \n \n \n
클릭하여 숫자를 변경하세요: \n\n
5씩 증가:
\n \n
0 \n\n
7씩 증가:
\n \n
0 \n\n
1씩 증가:
\n \n
0 \n\n
1씩 감소:
\n \n
0 \n
\n\nconst player = document.getElementById(\"player\");\n\n// 데이터 속성 값 읽기\nconsole.log(player.dataset.name); // \"김철수\"\nconsole.log(player.dataset.score); // \"100\"\nconsole.log(player.dataset.level); // \"5\"\n\n// 데이터 속성 값 수정\nplayer.dataset.score = \"150\"; // 점수를 150으로 업데이트\nplayer.dataset.rank = \"1\"; // 새로운 데이터 속성 추가\n\n// 데이터 속성 삭제\ndelete player.dataset.level; // level 속성 제거\n```\n\n**중요 사항:** `data-user-name`처럼 하이픈이 포함된 속성명은 `dataset.userName`처럼 camelCase로 자동 변환됩니다.\n\n### getAttribute/setAttribute: 전통적인 방법\n\n`dataset`이 더 편리하지만, 경우에 따라 전통적인 방법도 필요할 수 있습니다. 특히 동적으로 속성 이름을 생성해야 하는 경우에 유용합니다.\n\n```javascript\n// 전체 속성 이름을 명시해야 함\nconst score = player.getAttribute(\"data-score\"); // \"150\"\n\n// 속성 값 수정\nplayer.setAttribute(\"data-score\", \"200\");\n\n// 속성 제거\nplayer.removeAttribute(\"data-rank\");\n\n// 동적 속성 이름 생성\nconst statType = \"health\";\nplayer.setAttribute(`data-${statType}`, \"100\");\n```\n\n### 실전 예제: 카운터 구현\n\n```javascript\n// 모든 카운터 span 요소 선택\nconst counters = document.querySelectorAll(\"span[data-inc]\");\n\ncounters.forEach((counter) => {\n counter.addEventListener(\"click\", function () {\n // 현재 값과 증가값 가져오기\n const currentValue = parseInt(this.textContent);\n const increment = parseInt(this.dataset.inc);\n\n // 새로운 값 계산하고 표시\n this.textContent = currentValue + increment;\n });\n});\n```\n\n### 실전 예제: 필터링 시스템\n\n```html\n\n\n \n 필터링 시스템 예제 \n \n \n \n 필터링 시스템 \n\n \n
색상 \n \n
\n\n
크기 \n \n
\n
\n \n
빨강 작음
\n \n
빨강 큼
\n \n
파랑 작음
\n \n
파랑 큼
\n \n
노랑 작음
\n \n
노랑 큼
\n \n
빨강
\n \n
파랑
\n \n
노랑
\n \n
\n\nconst element = document.querySelector(\"div\");\n\n// kebab-case → camelCase 자동 변환\nconsole.log(element.dataset.userName); // \"홍길동\"\nconsole.log(element.dataset.phoneNumber); // \"010-1234-5678\"\n\n// JavaScript에서 camelCase로 설정하면\nelement.dataset.homeAddress = \"서울시 강남구\";\n// HTML에는 data-home-address=\"서울시 강남구\"로 저장됨\n```\n\n## 실무에서 바로 쓸 수 있는 예제들\n\n이제 지금까지 배운 내용을 바탕으로 실제 프로젝트에서 활용할 수 있는 완전한 예제들을 살펴보겠습니다. 이 예제들은 실무에서 바로 사용하거나 프로젝트에 응용할 수 있도록 구성했습니다.\n\n### 예제 1: 할 일 목록 (Todo List)\n\n```html\n\n\n \n \n \n \n \n \n 방 청소하기\n \n \n 책 읽기\n \n \n\n \n \n\n```\n\n### 예제 2: 이미지 갤러리\n\n```html\n\n\n \n \n \n \n \n\n \n
\n
\n
\n
\n
차트 업데이트 \n\n \n \n\n```\n\n## 알아두면 좋은 주의사항들\n\n데이터 속성을 효과적이고 올바르게 사용하기 위해 주의해야 할 사항들을 정리해보겠습니다.\n\n### 이런 건 하지 마세요! ❌\n\n이런 실수들은 초보자들이 자주 범하는 오류들입니다. 미리 알아두시면 시행착오를 줄일 수 있습니다.\n\n```html\n\n
\n\n
중요한 제목 \n\n\n\n
\n\n
\n\n\n\n
\n\n
\n\n```\n\n### 이렇게 하면 완벽해요! ✅\n\n다음과 같이 사용하면 깔끔하고 유지보수하기 쉬운 코드를 작성할 수 있습니다.\n\n```html\n\n삭제 \n\n\n\n\n\n
\n\n```\n\n### 성능도 생각해야죠\n\n데이터 속성을 많이 사용할 때는 성능에 대한 고려도 필요합니다. 여러 개의 속성을 한 번에 처리하는 것이 효율적입니다.\n\n```javascript\n// 데이터 속성이 많을 때는 한 번에 처리하기\nconst element = document.querySelector(\".product\");\n\n// 비효율적 ❌\nelement.dataset.name = \"노트북\";\nelement.dataset.price = \"1000000\";\nelement.dataset.category = \"전자제품\";\n\n// 효율적 ✅\nObject.assign(element.dataset, {\n name: \"노트북\",\n price: \"1000000\",\n category: \"전자제품\",\n});\n```\n\n### 브라우저 호환성은 걱정 마세요!\n\n다행히 데이터 속성은 오래전부터 대부분의 브라우저에서 지원되어 왔습니다.\n\n데이터 속성은 모든 최신 브라우저에서 지원됩니다:\n\n- Chrome ✅\n- Firefox ✅\n- Safari ✅\n- Edge ✅\n- Internet Explorer 11 ✅\n\n## 마무리\n\n이번 글에서는 HTML 데이터 속성의 개념부터 실제 활용 방법까지 자세히 살펴보았습니다.\n\nHTML 데이터 속성은 웹 개발에서 매우 유용한 기능입니다. 핵심 내용을 정리해보면 다음과 같습니다:\n\n📝 **HTML**에서 `data-*` 형식으로 구조화된 정보를 저장하고 \n🎨 **CSS**에서 속성 선택자와 `attr()` 함수를 활용해 동적인 스타일링을 구현하고 \n⚡ **JavaScript**에서 `dataset` 속성을 통해 효율적으로 데이터를 조작할 수 있습니다.\n\n이러한 활용법을 잘 익혀두면 더욱 체계적이고 유지보수가 쉬운 웹 애플리케이션을 개발할 수 있습니다.\n",
"content_text": "HTML data 속성 활용법부터 CSS attr() 함수, JavaScript dataset까지. 실무 예제로 배우는 데이터 속성 완전 가이드",
"url": "https://leeduhan.github.io/posts/css/html-data-attributes-guide/",
"date_published": "2025-07-27T00:00:00.000Z",
"authors": [
{
"name": "hanlee",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"HTML",
"CSS",
"JavaScript",
"Data Attributes",
"dataset",
"attr()",
"DOM",
"웹개발"
]
},
{
"id": "https://leeduhan.github.io/posts/react/2025-07-23-react-typing-component/",
"title": "React 타이핑 효과 컴포넌트 만들기 - HTML 태그와 이모지 완벽 지원",
"content_html": "\n타이핑 효과는 웹사이트에 생동감을 더하고 사용자의 주의를 끌 수 있는 효과적인 방법입니다. 이번 포스트에서는 React로 타이핑 효과 컴포넌트를 만드는 방법을 상세히 알아보겠습니다. 특히 HTML 태그와 복잡한 이모지를 완벽하게 지원하는 고급 기능까지 구현해보겠습니다.\n\n## 주요 기능\n\n우리가 만들 타이핑 컴포넌트의 주요 기능은 다음과 같습니다:\n\n- ✨ ReactNode children 지원 (HTML 태그 포함)\n- 🎯 복잡한 이모지 완벽 지원 (👨💻, 🧑🏻💻 등)\n- ⚡ 즉시 표시 모드 지원\n- ⏸️ 일시정지/재개 기능\n- 🎨 커스터마이징 가능한 스타일\n- 🔄 ref를 통한 제어 메서드 제공\n\n## 컴포넌트 인터페이스 정의\n\n먼저 컴포넌트의 Props와 Ref 인터페이스를 정의합니다:\n\n```typescript\nexport interface TypingProps {\n children: ReactNode; // 타이핑할 콘텐츠\n speed?: number; // 글자당 타이핑 속도 (ms)\n showCursor?: boolean; // 커서 표시 여부\n onComplete?: () => void; // 타이핑 완료 시 콜백\n className?: string; // 컨테이너 클래스명\n cursorClassName?: string; // 커서 추가 클래스명\n immediate?: boolean; // 즉시 표시 모드\n initialPaused?: boolean; // 일시정지 상태로 시작\n}\n\nexport interface TypingRef {\n reset: () => void; // 타이핑을 처음부터 다시 시작\n pause: () => void; // 타이핑 일시정지\n resume: () => void; // 타이핑 재개\n complete: () => void; // 타이핑을 즉시 완료\n}\n```\n\n## 핵심 구현\n\n### 1. ReactNode를 HTML 문자열로 변환\n\n가장 먼저 해결해야 할 문제는 ReactNode를 HTML 문자열로 변환하는 것입니다. 이를 통해 JSX로 작성된 복잡한 구조도 타이핑 효과로 표현할 수 있습니다:\n\n```typescript\nconst convertedText = useMemo(() => {\n // ReactNode를 문자열로 변환하는 재귀 함수\n const nodeToString = (node: ReactNode): string => {\n // 문자열이나 숫자인 경우 그대로 반환\n if (typeof node === 'string' || typeof node === 'number') {\n return String(node);\n }\n\n // 배열인 경우 각 요소를 변환하고 합침\n if (Array.isArray(node)) {\n return node.map(nodeToString).join('');\n }\n\n // React 엘리먼트인 경우\n if (node && typeof node === 'object' && 'props' in node) {\n const element = node as any;\n const { children: elementChildren, ...props } = element.props || {};\n\n // HTML 태그 생성\n const tagName = element.type || 'span';\n \n // 속성 처리 (className → class, style 객체 → 문자열 등)\n const attributes = Object.entries(props)\n .filter(([key]) => key !== 'children')\n .map(([key, value]) => {\n if (key === 'className') {\n return `class=\"${value}\"`;\n }\n if (key === 'style' && typeof value === 'object' && value !== null) {\n // style 객체를 CSS 문자열로 변환\n const styleStr = Object.entries(value)\n .map(([k, v]) => `${k.replace(/([A-Z])/g, '-$1').toLowerCase()}:${v}`)\n .join(';');\n return `style=\"${styleStr}\"`;\n }\n return `${key}=\"${value}\"`;\n })\n .join(' ');\n\n const openTag = `<${tagName}${attributes ? ' ' + attributes : ''}>`;\n const closeTag = ``;\n const childContent = elementChildren ? nodeToString(elementChildren) : '';\n\n return `${openTag}${childContent}${closeTag}`;\n }\n\n return '';\n };\n\n return nodeToString(children);\n}, [children]);\n```\n\n### 2. 이모지 및 복합 문자 처리\n\n복잡한 이모지(예: 👨💻, 🧑🏻💻)는 여러 개의 유니코드 문자가 결합된 형태입니다. 이를 올바르게 처리하려면 특별한 로직이 필요합니다:\n\n```typescript\nconst getNextCharacterIndex = useCallback((text: string, currentIndex: number): number => {\n if (currentIndex >= text.length) {\n return currentIndex;\n }\n\n // 현재 문자의 코드 포인트 가져오기\n const codePoint = text.codePointAt(currentIndex);\n if (!codePoint) {\n return currentIndex + 1;\n }\n\n // 서로게이트 페어 처리 (4바이트 유니코드)\n // 0xFFFF보다 큰 코드 포인트는 2개의 16비트 값으로 표현됨\n if (codePoint > 0xffff) {\n return currentIndex + 2;\n }\n\n // 이모지 범위 확인 함수\n const isEmoji = (code: number): boolean => {\n return (\n (code >= 0x1f600 && code <= 0x1f64f) || // Emoticons\n (code >= 0x1f300 && code <= 0x1f5ff) || // Misc Symbols and Pictographs\n (code >= 0x1f680 && code <= 0x1f6ff) || // Transport and Map\n (code >= 0x1f1e6 && code <= 0x1f1ff) || // Regional indicators\n (code >= 0x2600 && code <= 0x26ff) || // Misc symbols\n (code >= 0x2700 && code <= 0x27bf) || // Dingbats\n (code >= 0xfe00 && code <= 0xfe0f) || // Variation Selectors\n (code >= 0x1f900 && code <= 0x1f9ff) || // Supplemental Symbols and Pictographs\n (code >= 0x1f018 && code <= 0x1f270) || // Various symbols\n code === 0x200d || // Zero Width Joiner (ZWJ)\n code === 0x20e3 // Combining Enclosing Keycap\n );\n };\n\n // 이모지인 경우 복합 이모지 확인\n if (isEmoji(codePoint)) {\n let nextIndex = currentIndex + (codePoint > 0xffff ? 2 : 1);\n\n // 복합 이모지 처리 (ZWJ 시퀀스, 스킨톤 수식어 등)\n while (nextIndex < text.length) {\n const nextCodePoint = text.codePointAt(nextIndex);\n if (!nextCodePoint) {\n break;\n }\n\n // Zero Width Joiner나 Variation Selector가 있으면 계속 진행\n if (\n nextCodePoint === 0x200d || // ZWJ (이모지 결합자)\n (nextCodePoint >= 0xfe00 && nextCodePoint <= 0xfe0f) || // Variation Selectors\n (nextCodePoint >= 0x1f3fb && nextCodePoint <= 0x1f3ff) || // Skin tone modifiers\n nextCodePoint === 0x20e3 // Combining Enclosing Keycap\n ) {\n nextIndex += nextCodePoint > 0xffff ? 2 : 1;\n\n // ZWJ 다음에 오는 이모지도 포함\n if (nextCodePoint === 0x200d && nextIndex < text.length) {\n const followingCodePoint = text.codePointAt(nextIndex);\n if (followingCodePoint && isEmoji(followingCodePoint)) {\n nextIndex += followingCodePoint > 0xffff ? 2 : 1;\n }\n }\n } else {\n break;\n }\n }\n\n return nextIndex;\n }\n\n // 일반 문자는 1글자씩\n return currentIndex + 1;\n}, []);\n```\n\n### 3. 문자 경계 사전 계산\n\n성능 최적화를 위해 텍스트가 변경될 때 문자 경계를 미리 계산합니다. 이렇게 하면 타이핑 애니메이션 중에 복잡한 계산을 반복하지 않아도 됩니다:\n\n```typescript\nuseEffect(() => {\n textContentRef.current = convertedText;\n\n // immediate 모드일 경우 즉시 전체 텍스트 표시\n if (immediate) {\n setDisplayedContent(convertedText);\n setIsComplete(true);\n onComplete?.();\n return;\n }\n\n // 문자 경계를 미리 계산\n const boundaries: number[] = [0];\n let i = 0;\n\n while (i < convertedText.length) {\n if (convertedText[i] === '<') {\n // HTML 태그는 전체를 하나의 단위로 처리\n const tagEnd = findTagEnd(convertedText, i);\n i = tagEnd;\n } else {\n // 일반 문자나 이모지 처리\n i = getNextCharacterIndex(convertedText, i);\n }\n boundaries.push(i);\n }\n\n characterBoundariesRef.current = boundaries;\n reset();\n}, [convertedText, reset, findTagEnd, getNextCharacterIndex, immediate, onComplete]);\n```\n\n### 4. 타이핑 애니메이션 구현\n\nrequestAnimationFrame을 사용하여 부드러운 타이핑 애니메이션을 구현합니다:\n\n```typescript\nuseEffect(() => {\n if (\n !textContentRef.current ||\n isPaused ||\n isComplete ||\n characterBoundariesRef.current.length === 0 ||\n immediate\n ) {\n return;\n }\n\n let boundaryIndex = 0;\n\n const typeWriter = (timestamp: number) => {\n // 시간 추적을 위한 초기화\n if (!lastTimeRef.current) {\n lastTimeRef.current = timestamp;\n }\n\n const elapsed = timestamp - lastTimeRef.current;\n totalTimeRef.current += elapsed;\n lastTimeRef.current = timestamp;\n\n const text = textContentRef.current;\n const boundaries = characterBoundariesRef.current;\n\n // speed 밀리초마다 한 문자씩 추가\n while (totalTimeRef.current >= speed && boundaryIndex < boundaries.length - 1) {\n boundaryIndex++;\n\n // HTML 태그가 아닌 경우에만 시간 소모\n // (태그는 즉시 렌더링되어야 하므로)\n const currentPos = boundaries[boundaryIndex - 1];\n if (currentPos < text.length && text[currentPos] !== '<') {\n totalTimeRef.current -= speed;\n }\n }\n\n // 현재 경계까지의 내용 렌더링\n const currentBoundary = boundaries[Math.min(boundaryIndex, boundaries.length - 1)];\n const currentContent = text.substring(0, currentBoundary);\n setDisplayedContent(currentContent);\n\n // 타이핑이 완료되었는지 확인\n if (boundaryIndex >= boundaries.length - 1) {\n setIsComplete(true);\n animationIdRef.current = null;\n onComplete?.();\n } else if (!isPaused) {\n // 다음 프레임 요청\n animationIdRef.current = requestAnimationFrame(typeWriter);\n }\n };\n\n // 애니메이션 시작\n animationIdRef.current = requestAnimationFrame(typeWriter);\n\n // 클린업 함수\n return () => {\n if (animationIdRef.current) {\n cancelAnimationFrame(animationIdRef.current);\n animationIdRef.current = null;\n }\n };\n}, [speed, onComplete, isPaused, isComplete, immediate]);\n```\n\n### 5. 커서 애니메이션\n\nCSS 모듈을 사용하여 깜빡이는 커서를 구현합니다:\n\n```css\n/* typing.module.css */\n@keyframes blink {\n 0% {\n opacity: 1;\n }\n 50% {\n opacity: 0;\n }\n 100% {\n opacity: 1;\n }\n}\n\n.cursor {\n animation: blink 0.7s infinite;\n}\n```\n\n## 사용 예제\n\n### 기본 사용법\n\n```tsx\n\n 안녕하세요! 타이핑 효과 예제입니다.\n \n```\n\n### HTML 태그와 스타일 포함\n\n```tsx\n\n 오늘의 중요한 일정을\n \n```\n\n### Ref를 통한 제어\n\n```tsx\nconst typingRef = useRef(null);\n\nreturn (\n \n
\n 제어 가능한 타이핑 텍스트입니다.\n \n \n
\n typingRef.current?.pause()}>일시정지 \n typingRef.current?.resume()}>재개 \n typingRef.current?.reset()}>리셋 \n typingRef.current?.complete()}>완료 \n
\n
\n setStep(1)}\n >\n 첫 번째 메시지입니다.\n \n \n {step >= 1 && (\n setStep(2)}\n >\n 두 번째 메시지가 나타납니다.\n \n )}\n \n {step >= 2 && (\n \n 마지막 메시지입니다! 🎉\n \n )}\n
\n);\n```\n\n## 성능 최적화\n\n이 컴포넌트는 다음과 같은 성능 최적화 기법을 사용합니다:\n\n1. **useMemo**: ReactNode to HTML 변환 결과를 메모이제이션\n2. **useCallback**: 자주 호출되는 함수들을 메모이제이션\n3. **사전 계산**: 문자 경계를 미리 계산하여 애니메이션 중 연산 최소화\n4. **requestAnimationFrame**: 브라우저의 리페인트 주기에 맞춘 부드러운 애니메이션\n\n## 마무리\n\n이렇게 구현한 타이핑 컴포넌트는 단순한 텍스트뿐만 아니라 복잡한 HTML 구조와 이모지도 완벽하게 처리할 수 있습니다. ref를 통한 제어 기능으로 다양한 인터랙션도 구현할 수 있어 실제 프로젝트에서 유용하게 사용할 수 있을 것입니다.\n\n[React 공식 문서](https://react.dev/)의 권장사항에 따라 React 19의 새로운 기능들을 활용하여 구현했으며, TypeScript로 타입 안전성도 확보했습니다. 이 컴포넌트를 기반으로 여러분만의 창의적인 타이핑 효과를 만들어보세요!",
"content_text": "React에서 타이핑 효과를 구현하는 컴포넌트를 만들어봅니다. ReactNode children 지원, 복잡한 이모지 처리, 일시정지/재개 기능 등 다양한 기능을 포함한 완성도 높은 컴포넌트를 구현합니다.",
"url": "https://leeduhan.github.io/posts/react/2025-07-23-react-typing-component/",
"date_published": "2025-07-23T00:00:00.000Z",
"authors": [
{
"name": "",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"React",
"TypeScript",
"Component",
"Animation",
"UI",
"Typing Effect React component"
]
},
{
"id": "https://leeduhan.github.io/posts/claude/2025-07-11-claude-code-review/",
"title": "AI는 내 일자리의 강탈자가 아니다. 내 동료이고 스승이며 후임이다.",
"content_html": "\n# AI는 내 일자리의 강탈자가 아니다. 내 동료이고 스승이며 후임이다.\n\nAI를 사용하면서 느낀 것은 AI가 내가 처음 학습을 시작할 때 모르는 것을 알려주는 좋은 스승이자, 코드를 작성할 때 어떻게 구현하는 것이 좋은지 토론할 수 있는 동료이자, 실제 작업을 진행할 때 방법을 학습시키고 제대로 구현되었는지 확인하는 후임 같은 존재라는 것이다.\n\n함께 가는 동반자이지 나를 대체하는 존재가 아니다. 다만 학습해야 하는 방향성이나 업무 패러다임은 많은 변화가 있을 것이 확실하다. 하지만 개발 자체를 대체하지는 않는다는 것도 사실이다.\n\n## 결국은 사람이 해야 한다\n\nAI가 모든 것을 다 해주는 것 같지만, 결국 무엇을 해야 할지 정하고 어떤 방식으로 어떤 기술을 사용할지 결정하는 것은 사람이다. AI는 그 과정에서 고민하고 학습하고 커뮤니케이션하는 비용을 획기적으로 줄여줄 뿐, 실제 의사결정과 방향성 제시는 사람의 몫이다.\n\n비개발자도 AI의 도움으로 개발을 할 수 있다고 하지만, 이는 초기 단계에만 적용된다. 시스템이 복잡해질수록, 다양한 예외 상황을 고려해야 할수록 기본적인 개발 지식 없이는 진행이 어려워진다.\n\n또한 문제 해결 방법이 적절하지 않다면, 다음 문제를 해결할 때 기존 코드 구조가 모래성처럼 무너질 가능성이 높다. 이를 방지하려면 AI가 올바른 학습을 해야 하고, **학습의 내용과 품질, 그리고 방향을 결정하고 지도하는 주체는 결국 사람**이어야 한다. \n\n## CLI 버전의 무한한 가능성\n\nCLI 버전이야말로 개발 AI 도구로서 가장 완벽하다고 생각한다. 터미널상에서 사용할 수 있는 기본 모듈이나 표준화된 도구들이 매우 많고, AI는 이러한 도구들을 매우 잘 활용한다. 그래서 일반적으로 이야기하는 워크플로우도 별다른 설정 없이 미리 정해진 프롬프트만 실행하면 웬만한 워크플로를 구축할 수 있다. 여기에 [MCP(Model Context Protocol)](https://modelcontextprotocol.io/)까지 연결하게 되면 가능성은 더욱 확장된다.\n\n예를 들어, 일정 시간마다 나에게 할당된 Jira 티켓이 있는지 확인해서 대기 중인 티켓만 골라 각각의 티켓을 해결하는 worktree를 생성하고, 개별로 작업을 수행한 후 그 결과를 PR로 자동 생성하는 워크플로우를 구축하고 싶다고 하자.\n\n먼저 Jira를 MCP로 연결하거나 curl로 [Jira REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)에 접근해서 나에게 할당된 티켓 정보를 가져올 수 있다. 이 중에서 특정 상태인 티켓만 필터링하는 것도 가능하다. 이 과정도 API 문서만 제공해서 학습시키면 관련된 동작을 잘 수행할 것이고, 성공한 결과를 가지고 프롬프트로 만들어서 실행해 보면서 예외 케이스를 추가하면 된다.\n\n여기까지 되면 Jira 티켓 번호로 로컬에 브랜치를 생성하게 하면 된다. Git 터미널도 있고 [GitHub API](https://docs.github.com/en/rest)도 존재하기 때문에 이를 이용해서 브랜치를 생성하게 하고, Jira의 내용을 바탕으로 문제를 해결하는 코드를 스스로 작성하게 할 수도 있다.\n\n그다음에 작업이 완료되었다고 판단되면 PR을 원격에 생성하게 하면 된다. 개발자는 이 생성된 PR을 검토하거나 브랜치를 로컬로 가져와서 실행해 보면서 수정사항이나 미비 사항을 Jira에 남기거나 PR에 리뷰로 남기면, AI가 이를 다시 인식하게 할 수 있다 (인식시키는 방법은 Git 트리거를 사용하거나 일정 시간마다 호출하는 방식을 사용하면 된다).\n\n이 과정을 반복하다 보면 자잘한 이슈는 자동으로 해결되고, 사람은 AI가 처리하기 어려운 복잡한 문제나 제대로 구현되지 않은 부분만 처리하면 된다. 즉, 개발 생산성이 크게 향상되는 것이다.\n\n이렇게 터미널 기반으로 AI 개발 환경을 구현한다는 것은 생각보다 상상하는 모든 것을 가능하게 할 수도 있다.\n\n## 똑똑한 AI vs 성능이 낮은 AI\n\n[Claude](https://www.anthropic.com/claude), [Gemini](https://gemini.google.com/), [ChatGPT](https://openai.com/chatgpt), [Grok](https://grok.x.ai/) 등 여러 다양한 AI를 사용하다 보면 같은 질문에 전부 다른 답변을 한다. 답변의 품질은 결국 토큰을 얼마나 사용했느냐와 얼마나 많은 데이터로 학습되었느냐에 따라서 달라지는 것 같다.\n\n그렇다면 성능이 높은 AI가 항상 좋을까?\n\n실제 업무에 활용해보면서 느낀 것은 고성능 AI는 토큰을 많이 사용한다는 점이다. 즉, 비용이 문제가 된다. 그렇다고 저렴한 모델을 사용하면 답변의 품질이 문제가 된다.\n\n그렇다면 성능이 낮은 AI는 불필요한 것일까?\n\n사실 그렇지 않다. 결국 사람이 질문을 하는 것이기 때문에 질문의 수준과 난이도를 낮추면 토큰을 많이 사용하지 못하는 AI도 문제없이 작업을 수행하고 원하는 품질의 결과를 낸다. \n\n즉, 문제를 잘게 쪼개서 해당 AI가 질문을 이해하고 처리할 수 있는 토큰 사용량에 맞게 작업을 시키면 답변의 품질은 크게 차이나지 않는다.\n\n결국 핵심은 **AI의 토큰 사용량에 맞게 얼마나 작업을 작게 쪼개서 분배하고 다시 합칠 수 있느냐, 그 설계를 어떻게 할 것이냐**이다.\n\n토큰을 많이 소모하는 고성능 모델은 추상적이거나 애매한 질문에도 좋은 품질을 보여주기 때문에 복잡한 문제를 해결하거나 조각나 있는 프로젝트를 하나로 통합할 때 사용하면 좋다.\n\n반면 문제를 조각내서 작업하는 것은 저렴한 AI를 이용한다면 전체적인 토큰 소모량은 확실히 줄어들 것이다.\n\n소규모 작업에는 Gemini, Codex를 사용하고 이를 통합하거나 많은 추론이 필요한 작업은 Claude를 사용하는 것이 현재 시점에서 최적의 조합이라고 생각한다. \n\n만약 문제를 작게 나누어서 분배하고, 이를 검토하고 합치는 것까지 자동으로 할 수 있다면? 그런 AI 파이프라인을 구축할 수 있다면? 이것이 향후 발전 가능성이 높은 아키텍처가 아닐까? \n\n## AI 개발 워크플로우\n\n지금 내가 생각하는 AI 개발 워크플로우는 다음과 같다.\n\n```mermaid\n---\nconfig:\n layout: dagre\n---\nflowchart TD\n A[\"JIRA 등록\"] -- 웹훅 --> gemini\n A[\"JIRA 등록\"] -- 웹훅 --> claude\n A[\"JIRA 등록\"] -- 웹훅 --> user\n subgraph gemini\n g1{\"서브 테스크 작업별로 별도 worktree 생성\"}-->g2[[\"`작업진행`\"]]\n g2-->g21[\"PR 생성\"]\n g21-->g22[\"JIRA 상태 업데이트(작업완료)\"]\n g22-->g23[\"worktree 종료\"]\n g1-->g3[[\"`작업진행`\"]]\n g3-->g31[[\"`end-to-end 실행`\"]]\n g31-->g32[\"PR 생성\"]\n g32-->g33[\"JIRA 상태 업데이트(작업완료)\"]\n g33-->g34[\"worktree 종료\"]\n g1-->g4[[\"`작업진행`\"]]\n g4-->g41[[\"`tdd 실행`\"]]\n g41-->g42[\"PR 생성\"]\n g42-->g43[\"JIRA 상태 업데이트(작업완료)\"]\n g43-->g44[\"worktree 종료\"]\n end\n subgraph claude\n c1{\"JIRA 서브 테스크 진행상태 체크(전체 서브테스크가 작업완료 상태체크)\"}-->c2{\"서브테스크가 전부 작업완료 상태이면 worktree 생성\"}\n c2-->c21[[\"`각 PR을 받아서 하나의 브랜치에 병합`\"]]\n c21 --> c3[[\"`전체 화면 로직 개발`\"]]\n c3 --> c4[[\"`end-to-end 테스트`\"]]\n end\n subgraph user\n u1[\"슬랙등등.. 진행상황 전달\"]-->u2{\"전체로직이 완료되었는지 확인\"}\n u2 --> u3{\"원하는대로 구현되었는지 확인\"}\n u3 -. 구현 피드백 .-> u41[\"수정해야할 사항 확인\"]\n u41 --> u42[\"JIRA 서브티켓 생성\"]\n u3 -- 구현 완료 --> u4[\"배포\"]\n end\n```\n\n단계별로 살펴보면:\n\n### 1. JIRA 티켓 등록\n\n티켓을 등록하는 방법은 어떤 것이든 상관없다. 현재 JIRA를 사용해서 작업할 뿐이고 (개인적으로 JIRA가 불편하다고 생각한다), 어떤 프로젝트 관리 프로그램을 사용하든 상관없다. 다만 웹훅을 지원해주는 것이 좋다.\n\n티켓 구조는 스토리를 Claude가 처리할 티켓으로 정의하고, 하위 티켓으로 잘게 쪼개서 등록해야 한다. 스토리 티켓의 내용에는 하위 티켓을 어떻게 연결해서 어떤 기능을 만들 것인지, 최종 결과가 무엇인지를 명확하게 작성해야 한다.\n\n하위 티켓은 Gemini가 가져가서 개별로 작업할 티켓이다. Gemini를 선택한 이유는 토큰 소모율이 현재 가장 낮다고 생각되기 때문이다. 토큰을 많이 사용하지 못하고 성능이 제한적이므로, 작업을 나눌 수 있는 만큼 잘게 쪼개서 상세하게 작성해야 한다.\n\n티켓에는 작업 후 TDD, end-to-end 테스트를 어떻게 할 것인지에 대한 내용도 포함해야 한다.\n\n### 2. 작업별로 worktree 생성\n\n웹훅은 Gemini와 Claude 둘 다에게 전달된다. Gemini는 서브태스크의 상태가 진행 중인 경우에만 작업을 수행한다. Claude는 전체 서브태스크의 상태를 확인한 후, 모든 서브태스크가 완료된 경우에만 작업을 수행한다.\n\nGemini는 JIRA 티켓의 내용을 바탕으로 정해진 규칙에 따라서 worktree를 생성한다.\n\n티켓 내용대로 작업을 진행하고 테스트까지 통과되면 PR을 생성하고, JIRA 티켓의 상태를 작업 완료로 업데이트한다.\n\n### 3. 작업 통합 worktree 생성\n\nClaude는 모든 서브태스크가 완료된 경우에만 작업을 수행한다.\n\nworktree는 스토리 티켓의 번호로 생성하고, 각 서브태스크의 PR을 받아서 하나의 브랜치에 병합한다.\n\n병합이 완료되면 스토리 티켓의 내용을 바탕으로 전체 로직을 개발한다. 이때 end-to-end 테스트를 진행하고, 테스트가 통과되면 PR을 생성하고 JIRA 티켓의 상태를 작업 완료로 업데이트한다.\n\n### 4. 최종 검토 및 배포\n\n사용자의 검토는 최종 PR이 생성되었다는 알림을 Slack이나 다른 매체로 전달받으면 시작한다.\n\n사용자는 해당 기능이 제대로 동작하는지, 원하는 대로 구현되었는지 확인한다. 만약 수정해야 할 사항이 있다면 JIRA 티켓에 하위 티켓을 생성해서 Gemini가 작업을 진행하게 한다. 구현이 완료되었다면 배포를 진행한다.\n\n이 과정에서 사용자가 어느 타이밍에 개입하고, 무엇을 확인하거나 작업할지에 따라서 다양한 변형된 워크플로우가 만들어질 수 있다. 하지만 전체적인 흐름은 위와 동일할 것이라고 생각한다.\n\n### 실제 경험담\n\n한 달 동안 Claude Code로 개발할 때 2~3개의 worktree를 동시에 열고 각각의 작업을 진행하면서 느낀 점은 위와 같은 워크플로우가 가장 효율적이라는 것이다.\n\nAI가 작업하는 동안은 다른 worktree로 이동해서 다음 작업을 진행시키거나 작업된 사항을 검토해서 피드백하는 형태로 진행했다.\n\n#### 생산성 측정 결과\n\n생산성의 기준은 **작업 완료까지 걸린 시간**으로 측정했다.\n\n기준치(1.0)는 내가 혼자서 작업할 때 걸린 시간을 기준으로 했다. 작업은 보통 1시간 정도 걸리는 작업으로 측정했다.\n\n**측정 결과**: \n\n- **Claude Code**: 기준 대비 약 0.8 ~ 1.2 수준의 생산성\n- **Codex**: 기준 대비 약 0.3 ~ 0.5 수준의 생산성\n- **Copilot**: 기준 대비 약 0.5 ~ 0.8 수준의 생산성 (Claude 3.7 기준)\n\n초반에는 AI 사용법에 익숙하지 않아 오히려 시간이 더 오래 걸린 것도 있으므로 이를 감안해야 한다. 그리고 초반엔 잘못된 명령이나 잘못된 코드가 좀 있었다.\n\n**숙련 단계**: 기준치 대비 1.2~2.0 수준의 생산성 달성\n- **독립적인 작업**: 서로 연관성이 없는 작업으로 잘게 쪼개서 동시에 진행하면 최소 2배이상 가능\n- **연관성 있는 작업**: 작업 간 의존성이 있거나 하나씩 검토하며 진행할 때는 1.2배 수준 (약 20% 향상)\n- **작업을 세분화**: 작업을 더 작은 단위로 나누면 AI가 더 쉽게 이해하고 처리할 수 있다.\n- **학습 유무**: AI가 특정 작업에 대해 학습한 정도에 따라 생산성이 달라질 수 있다. 자주 쓰는 패턴이나 컴포넌트를 문서화해서 미리 학습시키고, 작업을 시키면 생산성이 크게 향상된다.\n\n결론적으로 **어떤 워크플로우를 설계하고 사용하느냐에 따라서 생산성은 크게 달라질 수 있다**는 것을 확인했다.\n\n## 작업 시 유의사항 \n\n1. **AI가 작업하는 동안 코드를 수정하지 말 것**: AI가 작업하는 동안 코드를 수정하면 AI가 이를 다시 읽어서 분석하기 때문에 토큰 소모량만 증가한다. 따라서 AI가 작업하는 동안은 다른 worktree로 이동해서 다음 작업을 진행하거나 작업된 사항을 검토해서 피드백하는 형태로 진행해야 한다.\n\n 같은 이유로 한 폴더에서 여러 개의 AI를 동시에 작업시키는 것도 좋지 않다. 파일이 변경될 때마다 서로 다시 읽기 때문이고, 작업이 서로 섞여서 AI끼리 작업 내용을 혼재해서 학습하게 된다.\n\n2. **작업을 잘게 쪼개서 분배할 것**: AI는 작업을 잘게 쪼개서 분배하면 더 쉽게 이해하고 처리할 수 있다. 따라서 작업을 세분화해서 AI가 처리할 수 있는 수준으로 나누는 것이 좋다.\n\n3. **질문은 구체적이고 명확하게 작성할 것**: AI에게 질문할 때는 구체적이고 명확하게 작성해야 한다. 애매하거나 추상적인 질문은 AI가 제대로 이해하지 못하고, 원하는 결과를 얻기 어렵다. \n\n## 작업 시 팁\n\n1. **AI의 학습을 돕는 문서화**: AI가 특정 작업에 대해 학습한 정도에 따라 생산성이 달라질 수 있다. 자주 사용하는 패턴이나 컴포넌트를 문서화해서 미리 학습시키고 작업을 시키면 생산성이 크게 향상된다.\n\n2. **도메인별 문서화**: 라이브러리를 만들거나 폴더로 도메인을 구분할 때 각각에 README.md를 만들어서 문서화해서 AI가 학습할 수 있도록 한다. AI가 해당 컴포넌트나 기능을 사용할 때 README.md를 읽고 학습할 수 있도록 한다.\n\n3. **간결한 문서 작성**: 프롬프트나 문서는 되도록 짧고 간결하게 작성하고, 가능한 AI가 작성하도록 한다. 사람이 작성한 경우 AI에게 먼저 학습시키고 결과를 확인한 후 피드백해서 다시 학습시킨 다음 이 과정을 문서화하라고 하면 된다.\n\n4. **단순 작업 활용**: AI의 생산성이 낮더라도 작업이 간단하거나 추상적인 지시사항이 없으면 AI가 작업을 잘 수행할 수 있다. \n\n## AI 시대의 개발자\n\nAI 시대의 개발은 위와 같은 패러다임 전환이 필요하다. AI가 도와주는 개발 환경을 구축하고, AI가 효율적으로 작업할 수 있는 환경을 만들어야 한다.\n\n앞으로 개발자는 AI와 직접 협업할 수도 있고, AI의 작업을 검토하고 지도하는 역할을 할 수도 있을 것이다.\n\n어느 쪽이든 **AI와의 협업을 통해 생산성을 극대화할 수 있느냐가 미래 개발자의 핵심 역량**이 될 것이다. ",
"content_text": "AI 개발 도구를 사용하면서 느낀 AI의 역할과 개발자의 미래에 대한 고찰",
"url": "https://leeduhan.github.io/posts/claude/2025-07-11-claude-code-review/",
"date_published": "2025-07-22T00:00:00.000Z",
"authors": [
{
"name": "zeke",
"url": "https://leeduhan.github.io"
}
],
"tags": [
"AI",
"Claude Code",
"개발 도구",
"생산성",
"워크플로우",
"Gemini"
]
},
{
"id": "https://leeduhan.github.io/posts/css/css-selecter-guide/",
"title": "CSS 선택자 완벽 가이드: 초보자를 위한 친절한 설명",
"content_html": "\n# 🎨 CSS 선택자 완벽 가이드\n\n안녕하세요! 오늘은 웹페이지를 꾸미는 핵심 도구인 **CSS 선택자**에 대해 알아보겠습니다. 색칠공부를 할 때 어떤 부분에 어떤 색을 칠할지 정하는 것처럼, CSS 선택자는 웹페이지의 어떤 부분을 꾸밀지 정하는 역할을 합니다.\n\n[MDN의 CSS 선택자 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)에 따르면, CSS는 60개 이상의 선택자와 5개의 결합자를 제공하여 HTML 요소를 정교하게 선택할 수 있습니다.\n\n## 📚 목차\n\n1. [CSS 선택자란?](#1-css-선택자란)\n2. [기본 선택자](#2-기본-선택자)\n3. [속성 선택자](#3-속성-선택자)\n4. [가상 클래스](#4-가상-클래스)\n5. [결합자](#5-결합자)\n6. [CSS 우선순위](#6-css-우선순위)\n7. [실습 예제](#7-실습-예제)\n\n---\n\n## 1. CSS 선택자란?\n\n`학급에서 특정 학생을 부를 때를 생각해보세요. \"안경 쓴 학생\", \"빨간 옷 입은 학생\", \"첫 번째 줄에 앉은 학생\" 이런 식으로 특징을 말해서 부르잖아요? CSS 선택자도 비슷한 방식으로 작동합니다!`\n\n[W3C의 Selectors Level 3 명세](https://www.w3.org/TR/2018/REC-selectors-3-20181106/)에 정의된 바와 같이, CSS 선택자는 HTML 문서의 특정 요소들을 선택하여 스타일을 적용하는 패턴입니다.\n\n```css\n/* 이게 바로 CSS의 기본 구조입니다 */\n선택자 {\n 꾸미기: 방법;\n}\n\n/* 실제 예시 */\np {\n color: blue; /* 모든 문단을 파란색으로 만들기 */\n}\n```\n\n---\n\n## 2. 기본 선택자\n\n### 🏷️ 태그 선택자 (Type Selector)\n\nHTML 태그 이름을 그대로 사용합니다. `마치 \"강아지\", \"고양이\"라고 종류별로 부르는 것과 같습니다.` [MDN 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors)에서는 이를 \"Type Selector\"라고 정의합니다.\n\n```html\n\n\n \n \n \n \n 빨간색 제목입니다 \n 초록색 문단입니다
\n 큰 버튼입니다 \n \n\n```\n\n### 🎯 클래스 선택자 (Class Selector)\n\n클래스는 여러 요소에게 같은 별명을 줄 수 있습니다. 점(.)으로 시작합니다! [MDN의 클래스 선택자 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/Class_selectors)에 따르면, 하나의 요소는 여러 개의 클래스를 가질 수 있습니다.\n\n```html\n\n\n \n \n \n \n 예쁜 분홍 배경입니다
\n 큰 글씨입니다
\n 예쁘고 크고 테두리도 있습니다
\n \n\n```\n\n### 🆔 ID 선택자 (ID Selector)\n\nID는 딱 하나의 요소만 가질 수 있는 고유한 이름입니다. 샵(#)으로 시작합니다! [MDN 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors)에 명시된 대로, HTML 문서 내에서 ID는 고유해야 합니다.\n\n```html\n\n\n \n \n \n \n 특별한 제목입니다 \n 금색 배경의 특별한 문단입니다
\n \n\n```\n\n### ✨ 전체 선택자 (Universal Selector)\n\n별표(\\*)는 \"모든 요소\"를 의미합니다. [MDN의 Universal Selector 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/Universal_selectors)에서 설명하듯이, 이 선택자는 모든 타입의 HTML 요소를 선택합니다.\n\n```html\n\n\n \n \n \n \n \n
박스 안의 제목 \n
박스 안의 문단
\n
박스 안의 텍스트 \n
나는 설명이 있어요!
\n\n \n\n PDF 문서 다운로드 \n \n\n```\n\n### 고급 속성 선택자\n\n```html\n\n\n \n \n \n \n 주요 버튼 \n 보조 버튼 \n 작은 버튼 \n\n 빨갛고 큰 글씨입니다
\n 파란 글씨입니다
\n \n\n```\n\n---\n\n## 4. 가상 클래스\n\n가상 클래스는 요소의 특별한 상태를 선택합니다. 콜론(:)으로 시작합니다! [MDN의 가상 클래스 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes)에 따르면, CSS는 80개 이상의 가상 클래스를 제공합니다.\n\n### 🖱️ 마우스 관련 가상 클래스\n\n```html\n\n\n \n \n \n \n 마우스를 올려보세요! 색이 변해요!
\n\n \n 구글 링크 \n 네이버 링크 \n
\n\n 마법 버튼을 눌러보세요! \n \n\n```\n\n### 📝 폼 관련 가상 클래스\n\n```html\n\n\n \n \n \n \n \n \n\n```\n\n### 🔢 순서 관련 가상 클래스\n\n```html\n\n\n \n \n \n \n \n 첫 번째 항목 (빨간색) \n 두 번째 항목 \n 세 번째 항목 (노란 배경) \n 네 번째 항목 \n 마지막 항목 (파란색) \n \n\n \n \n 1번 행 \n 홀수 \n \n \n 2번 행 \n 짝수 \n \n \n 3번 행 \n 홀수 \n \n \n 4번 행 \n 짝수 \n \n
\n\n \n
제목 \n
첫 번째 문단 (크고 초록색)
\n
두 번째 문단
\n
\n \n\n 섹션 1로 이동
\n 타겟이 된 섹션입니다!
\n\n 명언이 들어가는 곳
\n\n \n 옛날 옛적에 아주 작은 마을에 살고 있던 소녀가 있었습니다. 그 소녀는 매일\n 아침 일찍 일어나 정원에 물을 주었어요.\n
\n \n\n```\n\n---\n\n## 5. 결합자\n\n결합자는 선택자들 사이의 관계를 나타냅니다. `가족 관계처럼 생각하면 쉬워요!` [MDN의 결합자 문서](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Combinators)에서 4가지 주요 결합자를 설명합니다.\n\n### 후손 선택자 (Descendant Combinator)\n\n공백으로 표현되는 후손 선택자는 특정 요소의 모든 후손을 선택합니다.\n\n```html\n\n\n \n \n \n \n \n\n \n 메뉴1 \n 메뉴2 \n \n \n\n \n \n\n```\n\n### 자식 선택자 (Child Combinator)\n\n`>` 기호로 표현되는 자식 선택자는 직접적인 자식 요소만 선택합니다.\n\n```html\n\n\n \n \n \n \n \n
나는 직접 자식이라 빨간 테두리가 있어요!
\n
\n
\n \n 파란색 굵은 글씨\n \n 초록색 보통 글씨 \n 초록색 보통 글씨 \n \n \n 파란색 굵은 글씨 \n \n \n\n```\n\n### 인접 형제 선택자 (Next-sibling Combinator)\n\n`+` 기호로 표현되는 인접 형제 선택자는 바로 다음에 오는 형제 요소를 선택합니다.\n\n```html\n\n\n \n \n \n \n 제목입니다 \n 제목 바로 다음의 문단은 빨갛고 기울어져요!
\n 그 다음 문단은 평범해요.
\n\n 체크해보세요! \n\n 이미지 설명입니다.
\n \n\n```\n\n### 일반 형제 선택자 (Subsequent-sibling Combinator)\n\n`~` 기호로 표현되는 일반 형제 선택자는 이후에 오는 모든 형제 요소를 선택합니다.\n\n```html\n\n\n \n \n \n \n 주제 \n 첫 번째 문단
\n 두 번째 문단
\n 일반 div
\n 세 번째 문단
\n\n 특별한 div
\n 회색 배경 1
\n 회색 배경 2
\n 일반 문단
\n 회색 배경 3
\n \n\n```\n\n---\n\n## 6. CSS 우선순위\n\n여러 CSS 규칙이 충돌할 때, 어떤 규칙이 적용되는지 알아봅시다! [MDN의 명시도(Specificity) 문서](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity)에서 자세한 계산 방법을 확인할 수 있습니다.\n\n### 📊 우선순위(명시도) 계산 방법\n\nCSS 명시도는 **ID-CLASS-TYPE** 형식 (A-B-C)으로 계산됩니다:\n\n- **A**: ID 선택자의 개수\n- **B**: 클래스 선택자, 속성 선택자, 가상 클래스의 개수 \n- **C**: 타입 선택자와 가상 요소의 개수\n\n`비교할 때는 점수를 더하는 것이 아니라, 왼쪽 컬럼부터 차례로 비교합니다!`\n\n```html\n\n\n \n \n \n \n 기본 검정색 (0-0-1)
\n 파란색이 이김 (0-1-0 > 0-0-1)
\n 빨간색이 이김 (1-0-0 > 0-1-0)
\n ID가 있어서 빨간색 유지
\n \n\n```\n\n### 🎯 명시도 비교 원리\n\n```css\n/* 컬럼별 비교 방식 */\n.box /* 0-1-0 */\np.box /* 0-1-1 */\ndiv p.box /* 0-1-2 */ ← 가장 높음 (C 컬럼이 가장 큼)\n\n#header /* 1-0-0 */ ← 가장 높음 (A 컬럼이 있음)\n.nav .menu /* 0-2-0 */\n.nav ul li /* 0-1-2 */\n\n/* 컬럼별 비교 ✅ */\n/* 1-0-0 vs 0-2-0 → 첫 번째 컬럼에서 1 > 0이므로 #header 승리 */\n```\n\n### 🎯 우선순위 실전 예제\n\n```html\n\n\n \n \n \n \n \n
배경색: purple (!important 때문)
\n
\n
빨간색 (상속)
\n
파란색 (직접 지정)
\n
초록색 (인라인 스타일)
\n
기본 버튼 \n 빨간 버튼 \n 파란 버튼 \n \n\n```\n\n### 📋 체크리스트 만들기\n\n```html\n\n\n \n \n \n \n \n \n\n```\n\n### 🎨 테이블 꾸미기\n\n```html\n\n\n \n \n \n \n \n \n 과목 \n 점수 \n 등급 \n \n \n 국어 \n 95 \n A \n \n \n 수학 \n 88 \n B \n \n \n 영어 \n 92 \n A \n \n \n 과학 \n 86 \n B \n \n
\n \n\n```\n\n### 🎯 카드 레이아웃\n\n```html\n\n\n \n \n \n \n \n
\n
\n
\n
일반 카드 \n
이것은 일반적인 카드입니다.
\n
자세히 보기 \n
\n
\n\n
\n
\n
\n
특별한 카드 \n
이것은 추천 카드입니다!
\n
자세히 보기 \n
\n
\n\n
\n
\n
\n
또 다른 카드 \n
마우스를 올려보세요!
\n
자세히 보기 \n
\n
\n
=> {\n const response = await fetch(`/api/users/${userId}`)\n if (!response.ok) {\n throw new Error(`사용자를 찾을 수 없습니다: ${response.status}`)\n }\n return response.json()\n}\n\nconst fetchUserPosts = async (userId: string) => {\n const response = await fetch(`/api/users/${userId}/posts`)\n if (!response.ok) {\n throw new Error(`게시글을 불러올 수 없습니다: ${response.status}`)\n }\n return response.json()\n}\n```\n\n### 1. useQuery 사용 예시\n\n```typescript\nimport { useQuery } from '@tanstack/react-query'\n\nfunction UserProfileWithUseQuery({ userId }: { userId: string }) {\n const { \n data: user, \n isLoading, \n isError, \n error,\n isSuccess \n } = useQuery({\n queryKey: ['user', userId],\n queryFn: () => fetchUser(userId),\n enabled: !!userId, // 조건부 실행 가능\n staleTime: 5 * 60 * 1000, // 5분간 신선함 유지\n retry: 3, // 3번 재시도\n })\n\n // 로딩 상태 처리\n if (isLoading) {\n return (\n \n
\n
사용자 정보를 불러오는 중... \n
\n
오류가 발생했습니다 \n
{error?.message}
\n
window.location.reload()}\n className=\"mt-2 bg-red-500 text-white px-3 py-1 rounded hover:bg-red-600\"\n >\n 다시 시도\n \n
\n
\n {user.avatar && (\n
\n )}\n
\n
{user.name} \n
{user.email}
\n
\n
\n \n {/* 종속 쿼리 - 사용자 정보가 있을 때만 실행 */}\n
\n
게시글을 불러오는 중...
\n }\n\n if (error) {\n return 게시글 로딩 실패
\n }\n\n return (\n \n
최근 게시글 \n
\n {posts?.map((post: any) => (\n
\n
{post.title} \n
{post.excerpt}
\n
\n ))}\n
\n
유효하지 않은 사용자 ID입니다.
\n }\n\n return (\n \n
\n {user.avatar && (\n
\n )}\n
\n
{user.name} \n
{user.email}
\n
\n
\n \n {/* 종속 쿼리 */}\n
게시글을 불러오는 중... \n
최근 게시글 \n
\n {posts.map((post: any) => (\n
\n
{post.title} \n
{post.excerpt}
\n
\n ))}\n
\n
('123')\n\n return (\n \n
사용자 프로필 (useQuery) \n \n
\n
\n\n {/* 각 컴포넌트에서 개별적으로 로딩/에러 처리 */}\n
\n
('123')\n\n return (\n \n
사용자 프로필 (useSuspenseQuery) \n \n
\n
\n\n {/* 전역적인 로딩/에러 처리 */}\n
(\n \n
오류가 발생했습니다 \n
{error.message}
\n
\n 다시 시도\n \n
\n
\n 로딩 중... \n \n
\n
setSearchTerm(e.target.value)}\n placeholder=\"사용자 검색...\"\n className=\"w-full border rounded px-3 py-2\"\n />\n {isFetching && (\n \n )}\n \n\n {searchTerm.length > 0 && searchTerm.length <= 2 && (\n
3글자 이상 입력해주세요
\n )}\n\n {error && (\n
검색 중 오류가 발생했습니다
\n )}\n\n {isLoading && searchTerm.length > 2 && (\n
\n )}\n\n {data && (\n
\n
\n
\n {data.length}개의 결과\n
\n {isPreviousData && (\n
\n 업데이트 중...\n \n )}\n
\n
\n {data.map((user: User) => (\n
\n
{user.name} \n
{user.email}
\n
\n ))}\n
\n
\n )}\n
\n
setSearchTerm(e.target.value)}\n placeholder=\"사용자 검색...\"\n className=\"w-full border rounded px-3 py-2\"\n />\n\n {searchTerm.length > 0 && searchTerm.length <= 2 && (\n 3글자 이상 입력해주세요
\n )}\n\n {debouncedTerm.length > 2 && (\n (\n \n
검색 중 오류가 발생했습니다: {error.message}
\n
\n 다시 시도\n \n
\n
\n 검색 중...
\n \n
\n {data.length}개의 결과\n
\n
\n {data.map((user: User) => (\n
\n
{user.name} \n
{user.email}
\n
\n ))}\n
\n
사용자를 선택해주세요
\n \n const { data } = useSuspenseQuery({\n queryKey: ['user', userId],\n queryFn: () => fetchUser(userId)\n })\n ```\n\n2. **이전 데이터 유지**\n ```typescript\n // Before (useQuery)\n const { data, isPreviousData } = useQuery({\n queryKey: ['posts', page],\n queryFn: () => fetchPosts(page),\n keepPreviousData: true\n })\n\n // After (useSuspenseQuery + React Transitions)\n const [page, setPage] = useState(1)\n const [isPending, startTransition] = useTransition()\n \n const { data } = useSuspenseQuery({\n queryKey: ['posts', page],\n queryFn: () => fetchPosts(page)\n })\n\n const handlePageChange = (newPage: number) => {\n startTransition(() => {\n setPage(newPage)\n })\n }\n ```\n\n3. **에러 처리 구조 변경**\n ```typescript\n // Before - 컴포넌트별 에러 처리\n function Component() {\n const { data, error } = useQuery({...})\n if (error) return \n \n )\n }\n ```\n\n## 언제 어떤 것을 사용할까?\n\n### useQuery를 선택해야 하는 경우\n\n1. **세밀한 로딩 상태 제어가 필요한 경우**\n - 여러 부분에서 다른 로딩 UI를 보여줘야 할 때\n - 백그라운드 리페치 상태를 사용자에게 표시해야 할 때\n\n2. **조건부 쿼리가 많은 경우**\n - 폼 데이터나 사용자 입력에 따라 쿼리를 켜고 꺼야 할 때\n - 복잡한 의존성을 가진 쿼리들\n\n3. **점진적 마이그레이션**\n - 기존 프로젝트에서 단계적으로 도입할 때\n - 팀이 Suspense 패턴에 익숙하지 않을 때\n\n4. **이전 데이터 유지가 중요한 경우**\n - 페이지네이션, 필터링 등에서 깜빡임 없는 UX가 필요할 때\n\n### useSuspenseQuery를 선택해야 하는 경우\n\n1. **선언적 코드를 선호하는 경우**\n - 컴포넌트 로직을 단순화하고 싶을 때\n - 로딩/에러 상태 처리를 외부로 위임하고 싶을 때\n\n2. **TypeScript 타입 안전성이 중요한 경우**\n - `data`가 항상 정의되어 있음을 보장받고 싶을 때\n - 타입 가드 코드를 줄이고 싶을 때\n\n3. **현대적인 React 패턴을 활용하고 싶은 경우**\n - Concurrent Features와 함께 사용할 때\n - Server Components와 Streaming을 활용할 때\n\n4. **일관된 에러 처리 전략이 있는 경우**\n - 앱 전체에서 통일된 에러 UI를 제공하고 싶을 때\n\n## 성능 고려사항\n\n### 쿼리 워터폴 문제\n\n`useSuspenseQuery는 컴포넌트 트리에서 직렬로 실행되는 경향이 있습니다` (근거 없음):\n\n```typescript\n// 문제가 있는 패턴 - 직렬 실행\nfunction UserDashboard({ userId }: { userId: string }) {\n const { data: user } = useSuspenseQuery({\n queryKey: ['user', userId],\n queryFn: () => fetchUser(userId)\n })\n \n return (\n \n 프로젝트 로딩 중...
}>\n 로딩 중...}>\n \n )\n}\n\nfunction UserProfile({ userId }: { userId: string }) {\n const { data: user } = useSuspenseQuery({\n queryKey: ['user', userId],\n queryFn: () => fetchUser(userId)\n })\n return {user.name}
\n}\n\nfunction UserProjects({ userId }: { userId: string }) {\n const { data: projects } = useSuspenseQuery({\n queryKey: ['projects', userId],\n queryFn: () => fetchUserProjects(userId)\n })\n return {projects.length} 프로젝트
\n}\n```\n\n### 캐시 활용\n\n두 훅 모두 같은 QueryClient 캐시를 공유하므로 함께 사용할 수 있습니다:\n\n```typescript\n// useQuery로 프리페치\nfunction HomePage() {\n useQuery({\n queryKey: ['user', 'current'],\n queryFn: fetchCurrentUser,\n staleTime: Infinity, // 캐시에 오래 보관\n })\n \n return \n {({ reset }) => (\n (\n \n
문제가 발생했습니다 \n
\n 오류 상세 정보 \n {error.message} \n \n
\n 다시 시도\n \n
\n \n \n \n \n )}\n \n )\n}\n```\n\n### 2. 로딩 상태 최적화\n\n```typescript\n// 스켈레톤 UI 활용\nfunction ProductListSkeleton() {\n return (\n \n {Array.from({ length: 6 }).map((_, i) => (\n
\n ))}\n
\n {post.prev ? (\n \n );\n};\n// AIDEV-COMPLETE: 2024-01-15 기본 포스트 네비게이션 컴포넌트 생성\n// AIDEV-COMPLETE: 2024-01-20 홈으로 돌아가기 링크 추가 (이전글 없을 시)\n```\n\n### 앵커 코멘트 타입별 용도:\n\n- **`AIDEV-NOTE:`** - 코드 설명, 작동 방식, 중요한 맥락 정보\n- **`AIDEV-TODO:`** - 향후 구현해야 할 작업이나 개선사항\n- **`AIDEV-QUESTION:`** - 개발자에게 확인이 필요한 의문점이나 결정사항\n- **`AIDEV-RISK:`** - 예상되는 문제점, 주의사항, 금지된 행동\n- **`AIDEV-COMPLETE:`** - 완료된 작업 내역과 날짜\n\n### 앵커 코멘트 예시:\n\n```typescript\n// AIDEV-NOTE: 이 함수는 사용자 인증 상태에 따라 다른 UI를 렌더링\n// AIDEV-QUESTION: 로그아웃 상태에서도 프로필 정보를 캐시해야 하나?\n// AIDEV-RISK: 이 컴포넌트를 서버 컴포넌트로 변경하면 안됨 (클라이언트 상태 의존)\nconst UserProfile = () => {\n // 구현 코드...\n};\n// AIDEV-COMPLETE: 2024-01-10 기본 사용자 프로필 컴포넌트 구현\n// AIDEV-COMPLETE: 2024-01-12 로그인 상태 체크 로직 추가\n```\n\n### AIDEV-RISK 사용 예시:\n\n```typescript\n// AIDEV-RISK: 이 API는 rate limit이 있음 - 1초에 1회만 호출 가능\n// AIDEV-RISK: useState를 useRef로 바꾸면 안됨 (리렌더링 필요)\n// AIDEV-RISK: 이 함수는 메모리 누수 가능성 있음 - cleanup 함수 반드시 호출\nconst fetchUserData = async () => {\n // API 호출 코드...\n};\n```\n\n---\n\n## 6. Commit discipline\n\n- **Granular commits**: 논리적 변경사항당 하나의 커밋\n- **AI 생성 커밋 태깅**: 예: `feat: 포스트 네비게이션 추가 [AI]`\n- **명확한 커밋 메시지**: *why*를 설명; 아키텍처 관련이면 이슈/ADR 링크\n- **병렬/장기 AI 브랜치에 `git worktree` 사용**\n- **AI 생성 코드 리뷰**: 이해하지 못하는 코드는 절대 머지 금지\n\n---\n\n## AI Access Scope (AI 접근 범위)\n\n### ✅ AI가 할 수 있는 일\n\n#### 코드 구현\n\n- 명확한 명세를 바탕으로 **새로운 기능 작성**\n- 명확히 정의된 증상과 원인이 있는 **버그 수정**\n- 기존 패턴을 따라 **코드 리팩토링**\n- 기존 기능에 대한 **테스트 추가**\n- 구현된 기능에 대한 **문서 업데이트**\n- 기존 디자인에 맞는 **UI 컴포넌트 구현**\n- 프로젝트 패턴을 따라 **유틸리티 함수 생성**\n\n#### 코드 분석\n\n- 품질과 일관성을 위한 **코드 리뷰**\n- **버그와 잠재적 문제 식별**\n- **최적화 및 개선사항 제안**\n- **성능 병목 현상 분석**\n- **접근성 준수 확인**\n- **TypeScript 사용법과 타입 검증**\n\n#### 개발 지원\n\n- 템플릿을 따라 **보일러플레이트 코드 생성**\n- 기존 패턴을 기반으로 **설정 파일 생성**\n- 규칙을 따라 **커밋 메시지 작성**\n- 프로젝트 규칙에 따라 **코드 포맷팅 및 린팅**\n- **패키지 의존성 업데이트** (non-breaking)\n\n#### 개발 환경 관리 및 디버깅\n\n**✅ 허용된 활동:**\n\n- **로컬 개발 서버 실행**: 개발 모드에서만 서버 시작 (`pnpm dev`, `npm run dev`)\n- **로컬 빌드 테스트**: 개발 환경에서 빌드 검증 (`pnpm build`, `npm run build`)\n- **서버 콘솔 로그 모니터링**: 빌드 에러, 런타임 에러, 경고 메시지 확인\n- **MCP Puppeteer 활용**: 브라우저 자동화를 통한 실제 화면 테스트\n- **브라우저 콘솔 에러 감지**: JavaScript 에러, 네트워크 에러, 성능 이슈 확인\n- **실시간 에러 수정**: 발견된 에러를 즉시 분석하고 코드 수정으로 해결\n- **자동화된 에러 검증**: 코드 수정 후 Puppeteer를 통한 자동 테스트 및 검증\n\n**❌ 제한사항:**\n\n- **프로덕션 명령어 실행 금지**: `prod`, `build:prod`, `start:prod`, `build-standalone:prod` 등 프로덕션 관련 스크립트 실행 금지\n- **서버 시작 전 확인 필수**: 서버 실행 시 어느 환경(dev/staging/qa)으로 시작할지 사용자에게 확인 후 진행\n- **로컬 환경에서만 실행**: 원격 서버나 배포 환경에서 코드 실행 금지\n- **프로덕션 데이터 접근 금지**: 실제 사용자 데이터나 프로덕션 데이터베이스 접근 금지\n\n#### 서버 시작 절차\n\n1. **환경 확인**: 서버 시작 전 사용자에게 \"어느 환경으로 서버를 시작하시겠습니까?\" 질문\n2. **허용된 환경**: `dev`, `staging`, `qa` 등 개발/테스트 환경만 허용\n3. **금지된 환경**: `prod`, `production` 등 프로덕션 환경 금지\n4. **명령어 예시**:\n - ✅ `pnpm dev` (개발 서버)\n - ✅ `pnpm build` (로컬 빌드)\n - ✅ `pnpm start:staging` (스테이징 서버)\n - ❌ `pnpm start:prod` (프로덕션 서버 - 금지)\n\n#### 자동화된 코드 수정 검증 프로세스\n\nReact 컴포넌트나 클라이언트 사이드 코드를 수정한 후에는 위에서 정의한 **AI Assistant 자동화 규칙**의 검증 프로세스를 **반드시 자동으로 수행**해야 합니다.\n\n상세한 검증 프로세스는 상단의 \"AI Assistant 자동화 규칙\" 섹션을 참조하세요.\n\n### ❌ AI가 할 수 없는 일\n\n#### 중요한 결정사항\n\n- 승인 없이 **핵심 아키텍처 변경**\n- **데이터베이스 스키마**나 데이터 구조 수정\n- 다른 시스템에 영향을 주는 **API 계약 변경**\n- **보안 설정**이나 인증 업데이트\n- **빌드나 배포** 설정 변경\n- **환경 변수**나 시크릿 수정\n- Public API에 **breaking changes** 적용\n\n#### 민감한 작업\n\n- **프로덕션 데이터**나 시스템 접근\n- **사용자 권한**이나 역할 수정\n- **결제 처리** 로직 변경\n- **법적 준수** 코드 업데이트\n- **감사 로깅**이나 모니터링 수정\n- **데이터 프라이버시** 구현 변경\n\n#### 비즈니스 로직\n\n- **비즈니스 요구사항**이나 사용자 스토리 정의\n- **제품 결정**이나 기능 우선순위 설정\n- **가격**이나 비즈니스 모델 변경 결정\n- **준수 요구사항**이나 법적 제약 설정\n- 가이드 없이 **사용자 경험** 플로우 정의\n\n## Permitted Activities (허용된 활동)\n\n### 코드 개발\n\n#### ✅ 안전한 코드 변경\n\n```typescript\n// ✅ Adding new utility functions\nexport const formatCurrency = (amount: number): string => {\n return new Intl.NumberFormat(\"ko-KR\", {\n style: \"currency\",\n currency: \"KRW\",\n }).format(amount);\n};\n\n// ✅ Creating new UI components following patterns\nconst UserCard = ({ user }: { user: User }) => {\n return (\n \n {user.name} \n {user.email}
\n \n );\n};\n\n// ✅ Adding tests for existing functionality\ndescribe(\"formatCurrency\", () => {\n it(\"formats Korean currency correctly\", () => {\n expect(formatCurrency(1000)).toBe(\"₩1,000\");\n });\n});\n```\n\n#### ✅ 안전한 리팩토링\n\n```typescript\n// ✅ Extracting common logic into hooks\nconst useUserData = (userId: string) => {\n return useQuery({\n queryKey: [\"user\", userId],\n queryFn: () => fetchUserData(userId),\n });\n};\n\n// ✅ Simplifying component logic\nconst UserProfile = ({ userId }: { userId: string }) => {\n const { data: user, isLoading } = useUserData(userId);\n\n if (isLoading) return {\n // DON'T modify this without backend coordination\n data: T;\n status: number;\n}\n```\n\n### ❌ 보안에 민감한 코드\n\n```typescript\n// ❌ DON'T: Modify security configurations\nconst JWT_SECRET = process.env.JWT_SECRET; // DON'T change\nconst CORS_ORIGINS = [\"https://app.example.com\"]; // DON'T modify\n\n// ❌ DON'T: Change permission checks\nconst checkUserPermission = (user: User, action: string) => {\n // DON'T modify without security review\n};\n\n// ❌ DON'T: Update payment processing\nconst processPayment = (amount: number, method: PaymentMethod) => {\n // DON'T change without business approval\n};\n```\n\n### ❌ 프로덕션 설정\n\n```typescript\n// ❌ DON'T: Modify production environment variables\n// .env.production\nDATABASE_URL=... // DON'T change\nSTRIPE_SECRET_KEY=... // DON'T modify\nSENTRY_DSN=... // DON'T update\n\n// ❌ DON'T: Change build configurations without approval\n// next.config.mjs, docker files, CI/CD configs\n```\n\n## Code Quality Standards (코드 품질 기준)\n\n### 필수 기준\n\n#### TypeScript 사용\n\n- **엄격한 타이핑** - 정당한 이유 없이 `any` 타입 사용 금지\n- **인터페이스 정의** - 모든 데이터 구조 타입 지정\n- **제네릭 타입** - 재사용 가능한 타입 정의\n- **타입 import** - 타입과 값 import 분리\n\n#### 코드 구성\n\n- **기존 패턴 준수** - 현재 코드 스타일과 일치\n- **일관된 네이밍** - 기존 규칙 사용\n- **적절한 파일 구조** - 파일을 적절한 디렉토리에 배치\n- **명확한 분리** - 관심사를 적절히 분리\n\n#### 성능 고려사항\n\n- **import 최적화** - Tree-shaking 친화적인 import 사용\n- **메모이제이션** - React.memo, useMemo 적절히 사용\n- **번들 크기** - 정당한 이유 없이 큰 의존성 피하기\n- **지연 로딩** - 유익한 곳에서 코드 분할 구현\n\n## Safety Guidelines (안전 가이드라인)\n\n### 변경 전 확인사항\n\n#### 1. 컨텍스트 이해\n\n- 패턴을 이해하기 위해 **기존 코드 읽기**\n- 의존성을 위해 **관련 파일 확인**\n- 예상 동작을 이해하기 위해 **테스트 파일 검토**\n- 데이터 구조를 위해 **타입 정의 검토**\n\n#### 2. 접근 방식 검증\n\n- 요구사항이 불명확하면 **명확히 하기**\n- 개발자와 **breaking changes 확인**\n- 민감한 코드의 **보안 영향 검증**\n- 큰 변경의 **성능 영향 확인**\n\n#### 3. 철저한 테스트\n\n- 회귀 방지를 위해 **기존 테스트 실행**\n- 새로운 기능에 대한 **새 테스트 추가**\n- **엣지 케이스**와 에러 시나리오 테스트\n- UI 변경에 대한 **접근성 검증**\n\n### 에러 방지\n\n#### 피해야 할 일반적인 함정\n\n```typescript\n// ❌ DON'T: Make assumptions about data structure\nconst user = data.user.profile.settings; // Could be undefined\n\n// ✅ DO: Use safe navigation and validation\nconst settings = data?.user?.profile?.settings;\nif (!settings) {\n console.warn(\"User settings not found\");\n return defaultSettings;\n}\n\n// ❌ DON'T: Ignore TypeScript errors\nconst result = fetchData() as any; // Defeats type safety\n\n// ✅ DO: Proper type handling\nconst result = await fetchData();\nif (isValidResponse(result)) {\n // Handle typed result safely\n}\n```\n\n## Collaboration Principles (협업 원칙)\n\n### 소통 가이드라인\n\n#### 개발자와의 소통\n\n- 일반적인 질문보다 **구체적인 질문** 하기\n- 제안에 대한 **컨텍스트 제공**\n- 구현 뒤의 **논리적 근거 설명**\n- **피드백을 수용**하고 변경사항 반영\n- 구현 전에 **요구사항 명확히** 하기\n\n#### 코드 리뷰\n\n- 주석으로 **복잡한 로직 설명**\n- 구현 중 만든 **가정사항 문서화**\n- **잠재적 문제**나 엣지 케이스 강조\n- 적절할 때 **대안 제안**\n- **피드백에 열린 마음**과 변경 수용\n\n### 지식 전달\n\n#### 문서화\n\n- 변경 시 **관련 문서 업데이트**\n- 복잡한 로직에 **인라인 주석 추가**\n- 새로운 유틸리티에 대한 **예시 생성**\n- **Breaking changes를 명확히** 문서화\n\n#### 코드 주석\n\n```typescript\n// #user-validation: Input validation for user data\nconst validateUserInput = (input: UserInput): ValidationResult => {\n // Check required fields first to fail fast\n if (!input.email || !input.name) {\n return { isValid: false, errors: [\"Email and name are required\"] };\n }\n\n // Validate email format using RFC 5322 regex\n const emailRegex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n if (!emailRegex.test(input.email)) {\n return { isValid: false, errors: [\"Invalid email format\"] };\n }\n\n return { isValid: true, errors: [] };\n};\n```\n\n## Decision Making Framework (의사결정 프레임워크)\n\n### 독립적으로 진행 가능한 경우\n\n#### ✅ 구현해도 안전함\n\n- 모호함이 없는 **명확한 요구사항**\n- **기존 패턴을 정확히** 따르는 경우\n- **Non-breaking changes**만 있는 경우\n- **잘 정의된 테스트 케이스**가 있는 경우\n- **보안적 영향이 없는** 경우\n\n### 가이드를 요청해야 하는 경우\n\n#### ❓ 상담이 필요함\n\n- **불명확하거나 불완전한** 요구사항\n- **여러 유효한 접근법**이 가능한 경우\n- **Breaking changes**가 필요한 경우\n- **성능 영향**이 불분명한 경우\n- **보안 고려사항**이 관련된 경우\n- **외부 API 변경**이 필요한 경우\n\n### 에스컬레이션이 필요한 경우\n\n#### ⚠️ 반드시 에스컬레이션\n\n- **비즈니스 로직 결정**이 필요한 경우\n- **아키텍처 변경**이 필요한 경우\n- **프로덕션 이슈**가 발생한 경우\n- **보안 취약점**을 발견한 경우\n- **법적 또는 규정 준수** 영향이 있는 경우\n- **리소스 할당** 결정이 필요한 경우\n\n## Documentation Requirements (문서화 요구사항)\n\n### 코드 문서화\n\n#### 필수 주석\n\n```typescript\n/**\n * #payment-processing: Core payment handling logic\n *\n * Processes user payments through various payment methods.\n * Integrates with Stripe API and handles error scenarios.\n *\n * @param amount - Payment amount in cents\n * @param method - Payment method (card, bank, etc.)\n * @param userId - User making the payment\n * @returns Promise - Payment outcome\n *\n * @example\n * const result = await processPayment(1000, 'card', 'user123')\n * if (result.success) {\n * console.log('Payment successful:', result.transactionId)\n * }\n */\n```\n\n#### 변경사항 문서화\n\n- 규칙을 따르는 **커밋 메시지**\n- 변경사항을 설명하는 **PR 설명**\n- 복잡한 로직에 대한 **코드 주석**\n- **API 문서** 업데이트\n- Breaking changes에 대한 **마이그레이션 가이드**\n\n## 실제 작업 사례 (Real-world Examples)\n\n### React Key Prop 경고 수정 사례 (클라이언트 컴포넌트)\n\n다음은 실제로 수행된 자동화된 검증 프로세스의 사례입니다:\n\n#### 문제 상황\n\n- `item-product.client.tsx:192`에서 \"Each child in a list should have a unique key prop\" 경고 발생\n- React 개발 모드에서 콘솔에 경고 메시지 출력\n- 클라이언트 컴포넌트이므로 서버 재시작 불필요\n\n#### 자동 검증 프로세스 실행 (클라이언트 컴포넌트)\n\n1. **포트 번호 자동 탐지**:\n - `apps/web/.env.local` 확인 → `PORT=3000` 발견 ✅\n - MCP Puppeteer에서 `http://localhost:3000` 사용\n2. **서버 상태 확인**: `ps aux | grep next` 명령으로 개발 서버 실행 상태 확인 (재시작 안함)\n3. **컴포넌트 사용 경로 탐지**: `ItemProduct` 컴포넌트가 사용되는 모든 페이지 탐지\n4. **MCP Puppeteer 전체 경로 검증**: 홈페이지 및 관련 페이지들 순차 접속 (필수!)\n5. **특정 에러 모니터링**: key prop 경고만 감지, 기타 에러/경고 무시\n6. **코드 수정**: Fragment 대신 조건부 렌더링 사용, key prop 올바른 위치 이동\n7. **MCP Puppeteer 재검증**: 수정 후 모든 관련 페이지에서 key prop 경고 해결 확인 (필수!)\n8. **시각적 검증**: MCP Puppeteer 스크린샷으로 UI 정상 렌더링 확인\n\n#### 수정 내용\n\n```tsx\n// 수정 전 (❌ 잘못된 key prop 위치)\n{\n product.displayTags?.map((tag) => (\n <>\n {tag && (\n \n {\" \"}\n // map의 직접 자식에 key\n {tag && (\n
\n )}\n
안녕하세요, {user.name}님!
;\n}\n\nfunction App() {\n const userPromise = fetch(\"/api/user\").then((res) => res.json());\n\n return (\n 로딩중...}>\n \n );\n}\n```\n\n### useOptimistic() 훅\n\n낙관적 업데이트를 쉽게 구현할 수 있는 새로운 훅입니다:\n\n```javascript\nimport { useOptimistic, useState } from \"react\";\n\nfunction TodoList() {\n const [todos, setTodos] = useState([]);\n const [optimisticTodos, addOptimisticTodo] = useOptimistic(\n todos,\n (currentTodos, newTodo) => [...currentTodos, newTodo]\n );\n\n async function addTodo(formData) {\n const newTodo = { id: Date.now(), text: formData.get(\"text\") };\n\n // 즉시 UI 업데이트\n addOptimisticTodo(newTodo);\n\n // 서버에 실제 요청\n try {\n const savedTodo = await saveTodo(newTodo);\n setTodos((prev) => [...prev, savedTodo]);\n } catch (error) {\n // 에러 시 자동으로 이전 상태로 롤백\n console.error(\"할 일 저장 실패:\", error);\n }\n }\n\n return (\n \n {optimisticTodos.map((todo) => (\n
{todo.text}
\n ))}\n
\n
\n {post.title} \n {post.content}
\n \n );\n}\n```\n\n## 새로운 컴파일러\n\n### React Compiler\n\nReact 19에는 새로운 컴파일러가 포함되어 자동 최적화를 제공합니다:\n\n```javascript\n// 이제 수동으로 메모이제이션할 필요가 없습니다\nfunction ExpensiveComponent({ data, filter }) {\n // 컴파일러가 자동으로 최적화\n const filteredData = data.filter((item) => item.category === filter);\n\n const processedData = filteredData.map((item) => ({\n ...item,\n processed: true,\n }));\n\n return (\n \n {processedData.map((item) => (\n
{item.name}
\n ))}\n
\n
{user.name} \n
{user.email}
\n