feat: batch wikification of Skybound balance pass and scalable frontend architectures

Processed 80+ files including Skybound playtest feedback, Monorepo strategies, and Modern Component Patterns.
2026-04-26 13:53:50 +09:00
parent cfafbdbc36
commit f541717fe1
156 changed files with 6543 additions and 243 deletions
@@ -1,20 +1,25 @@
 # [[Next.js App Router]]

 ## 📌 Brief Summary
-Next.js App Router는 향상된 레이아웃 중첩(nesting)과 관심사 분리(separation of concerns)를 가능하게 하는 Next.js의 라우팅 구조입니다 [1]. 브라우저가 아닌 서버에서 실행되어 HTML을 스트리밍하는 React Server Components(RSC)를 활용하며 [2], 대규모 프론트엔드 프로젝트의 유지보수성을 높이기 위해서는 App Router에 최적화된 폴더 아키텍처 설계와 RSC에 호환되는 CSS 스타일링 전략의 선택이 필수적입니다 [3, 4].
+Next.js App Router는 React Server Components(RSC)를 핵심 아키텍처로 도입하여 기존의 클라이언트 측 렌더링 중심의 개발 방식에서 벗어난 새로운 패러다임을 제공하는 라우팅 시스템입니다 [1]. 기본적으로 모든 컴포넌트가 서버 컴포넌트로 동작하여 서버에서 HTML을 완전히 렌더링하며, 상태 관리나 이벤트 핸들러 등 상호작용이 필요한 경우에만 'use client' 지시어를 사용해 클라이언트 컴포넌트를 분리합니다 [2, 3]. 이러한 아키텍처 변화는 애플리케이션의 성능과 보안을 향상시키지만, 기존의 상태 및 컨텍스트 기반 스타일링 접근 방식에 중대한 영향을 미칩니다 [4, 5].

 ## 📖 Core Content
- **스타일링 호환성 및 RSC 문제 (The RSC Problem)**
-  Next.js App Router는 서버에서 실행되는 React Server Components(RSC)를 근간으로 합니다 [2]. 이 때문에 React Context에 의존하여 런타임에 스타일을 생성하는 기존의 CSS-in-JS 라이브러리(예: styled-components, Emotion)는 App Router 환경과 근본적으로 호환되지 않습니다 [2, 3]. 따라서 2025년 기준 App Router를 사용하는 프로젝트에서는 런타임 오버헤드가 없는 **Tailwind CSS**, **CSS Modules**, 또는 빌드 타임에 정적 CSS를 생성하는 **vanilla-extract**(zero-runtime CSS-in-JS)를 사용하는 것이 적극적으로 권장됩니다 [5, 6].
- **유지보수를 위한 확장 가능한 아키텍처 (Scalable Project Structure)**
-  App Router를 도입할 때 흔히 발생하는 실수는 `app/` 디렉토리 내에 라우트와 함께 모든 컴포넌트, 훅(hooks), 비즈니스 로직을 혼재시키는 것입니다 [4]. 애플리케이션이 복잡해질수록 이러한 구조는 관리가 불가능해지므로, `app/` 폴더(`page.tsx`, `layout.tsx` 등)는 라우팅과 레이아웃을 처리하는 목적으로만 단순하게 유지해야 합니다 [7, 8].
- **기능 주도 개발 (Feature-Driven Architecture) 적용**
-  파일들을 단순히 유형별(components, hooks, utils 등)로 묶는 대신, 비즈니스 기능이나 도메인 단위로 그룹화하는 기능 주도 아키텍처(Feature-Based Architecture)를 적용해야 확장에 유리합니다 [1, 4, 7]. 실제 비즈니스 로직과 UI 컴포넌트는 `src/features/`와 같은 디렉토리로 분리하고 [8], 데이터 패칭(API)과 비즈니스 로직을 UI 프레젠테이션 파일과 철저히 분리함으로써 안전한 리팩토링과 협업을 가능하게 해야 합니다 [1, 8].
+* **React Server Components(RSC) 모델의 작동 방식**
+  Next.js 15 App Router 환경에서 서버 컴포넌트는 클라이언트로 JavaScript 코드를 전송하지 않으며, 서버에서 직접 데이터를 패칭하여 렌더링된 HTML만을 브라우저로 보냅니다 [2]. 반면 동적 상태 변경, 브라우저 API 접근, 이벤트 리스너가 필요한 인터랙티브 UI는 파일 최상단에 `'use client'`를 명시하여 클라이언트 컴포넌트 경계(Client Component Boundary)를 설정해야 합니다 [3]. 하이드레이션(Hydration) 프로세스는 이러한 클라이언트 컴포넌트에 대해서만 수행되어 인터랙티비티를 활성화합니다 [6].
+
+* **스타일링 패러다임의 충돌 및 권장 사항**
+  RSC는 서버 전용 실행 환경으로, React Context를 사용할 수 없습니다 [7, 8]. 이는 테마나 상태를 위해 Context API에 의존하는 런타임 CSS-in-JS 라이브러리(styled-components, Emotion 등)가 App Router에서 기본적으로 작동하지 않는 문제를 발생시켰습니다 [4, 7, 8]. 따라서 Next.js App Router를 사용하는 최신 프로젝트에서는 런타임 오버헤드 없이 빌드 타임에 정적 CSS를 생성하는 **Tailwind CSS**, **CSS Modules**, 혹은 **vanilla-extract**(Zero-runtime CSS-in-JS)의 도입이 강력히 권장됩니다 [8-10].
+
+* **CSS-in-JS 지원 및 레지스트리 패턴**
+  Next.js 15는 런타임 CSS-in-JS 라이브러리를 사용할 수 있도록 렌더링 중 CSS 규칙을 수집하고 이를 HTML의 `<head>`에 주입(`useServerInsertedHTML` 훅 활용)하는 **Style Registry 패턴**을 지원합니다 [11]. 그러나 서버와 클라이언트의 클래스명 불일치(Hydration Mismatch)를 방지하기 위한 추가 설정(예: `next.config.js` 내 컴파일러 옵션)이 요구됩니다 [12]. 최신 `styled-components` (v6.3.0 이상)의 경우, RSC 환경을 자동 감지하여 별도의 설정 없이 인라인 `<style>` 태그를 방출하는 RSC 지원 업데이트를 추가하기도 했습니다 [13]. 
+
+* **렌더링 및 데이터 패칭 최적화 전략**
+  App Router는 사용 사례에 최적화하기 위해 빌드 타임에 미리 정적 HTML을 렌더링하는 정적 렌더링(Static Rendering, 기본값) 외에, 동적 렌더링(Dynamic Rendering), 점진적 정적 재생성(ISR, Incremental Static Regeneration) 등의 다양한 전략을 제공합니다 [14]. 데이터 패칭 시에도 병렬(Parallel) 데이터 패칭, 의존성에 따른 순차적(Sequential) 패칭, 그리고 React Suspense를 결합해 콘텐츠를 점진적으로 보여주는 스트리밍(Streaming) 패턴을 구성할 수 있습니다 [15].

 ## 🔗 Knowledge Connections
- **Related Topics:** [[React Server Components]], [[CSS Modules]], [[Tailwind CSS]], [[Feature-Driven Architecture]]
- **Projects/Contexts:** [[확장 가능한 프론트엔드 아키텍처 및 폴더 구조 설계]], [[대규모 앱의 유지보수를 위한 모던 CSS 도구 도입]]
- **Contradictions/Notes:** 런타임 CSS-in-JS(예: styled-components)는 기존 Pages Router 기반의 프로젝트에서는 문제없이 작동하지만, App Router로 마이그레이션할 경우 서버 컴포넌트 구조와의 충돌로 인해 동작하지 않으므로 Tailwind CSS, CSS Modules 또는 vanilla-extract 등으로 마이그레이션을 계획해야 합니다 [6].
+- **Related Topics:** [[React Server Components]], [[Tailwind CSS]], [[Styled Components]], [[Zero-runtime CSS-in-JS]], [[Hydration]]
+- **Projects/Contexts:** [[Modern Frontend Engineering]], [[Scalable Frontend Architecture]]
+- **Contradictions/Notes:** 소스 전반에서 기존 런타임 CSS-in-JS 라이브러리(styled-components 등)가 React Context 부재로 인해 Next.js App Router(RSC) 환경과 호환되지 않아 Tailwind CSS나 정적 CSS 방식이 권장된다고 설명합니다 [4, 7, 10]. 그러나 `styled-components`의 릴리스 노트를 보면 v6.3.0 이후부터 RSC 환경을 자동으로 감지하고 인라인 `<style>` 태그를 자체적으로 방출 및 병합하여 RSC 및 App Router에서도 정상 동작하도록 패치되었습니다 [13]. 

 ---
 *Last updated: 2026-04-26*