--- category: Unified tags: [auto-consolidated, technical-documentation] title: [[Next.js App Router 프로젝트|Next.js App Router 프로젝트]] last_updated: 2026-05-02 --- # [[Next.js App Router 프로젝트|Next.js App Router 프로젝트]] ## 📌 Brief Summary [[Next.js App Router|Next.js App Router]] 프로젝트는 React Server Components(RSC)를 기반으로 동작하기 때문에 기존의 런타임 CSS-in-JS(예: [[styled-components|styled-components]], Emotion) 라이브러리와는 호환되지 않아 스타일링 아키텍처의 변화가 필수적입니다 [1, 2]. 실무에서 유지보수성과 확장성을 확보하기 위해 스타일링은 **Tailwind CSS**, **[[CSS Modules|CSS Modules]]** 또는 빌드 타임 기반의 **[[vanilla-extract|vanilla-extract]]**를 사용하는 것이 권장됩니다 [2, 3]. 더불어 대규모 애플리케이션으로 확장하기 위해서는 `app/` 디렉토리에 모든 코드를 넣는 대신, 라우팅과 비즈니스 로직을 분리하는 **기능 주도(Feature-Driven)** 형태의 모듈러 폴더 구조를 채택해야 합니다 [4, 5]. --- [[Next.js App Router|Next.js App Router]] 환경에서는 React Server Components(RSC)와의 호환성 문제로 인해 기존의 런타임 CSS-in-JS(예: [[styled-components|styled-components]], Emotion) 사용이 부적합합니다 [1, 2]. 대신 확장성과 유지보수성을 위해 런타임 오버헤드가 없는 Tailwind CSS, [[CSS Modules|CSS Modules]], 또는 vanilla-extract와 같은 [[Zero-Runtime CSS-in-JS|Zero-Runtime CSS-in-JS]]의 사용이 권장됩니다 [2, 3]. 더불어 성공적인 컴포넌트 스타일링과 관리를 위해서는 라우팅 구조와 비즈니스 로직 및 UI 컴포넌트를 분리하는 기능 기반(Feature-Driven) 아키텍처의 도입이 필수적입니다 [4]. --- [[Next.js|Next.js]] App Router는 [[React Server Components|React Server Components]](RSC)를 핵심 아키텍처로 도입하여 기존의 클라이언트 측 렌더링 중심의 개발 방식에서 벗어난 새로운 패러다임을 제공하는 라우팅 시스템입니다 [1]. 기본적으로 모든 컴포넌트가 서버 컴포넌트로 동작하여 서버에서 HTML을 완전히 렌더링하며, 상태 관리나 이벤트 핸들러 등 상호작용이 필요한 경우에만 'use client' 지시어를 사용해 클라이언트 컴포넌트를 분리합니다 [2, 3]. 이러한 아키텍처 변화는 애플리케이션의 성능과 보안을 향상시키지만, 기존의 상태 및 컨텍스트 기반 스타일링 접근 방식에 중대한 영향을 미칩니다 [4, 5]. ## 📖 Core Content * **스타일링 전략 및 CSS 아키텍처** * [[Next.js|Next.js]] App Router는 서버에서 HTML을 스트리밍하는 **React Server Components(RSC)**를 사용하므로, [[React Context|React Context]]에 의존하는 런타임 CSS-in-JS는 기능할 수 없으며 App Router를 사용하는 새 프로젝트에는 권장되지 않습니다 [1, 2, 6]. * 따라서 런타임 오버헤드가 없는 **Tailwind CSS**나 로컬 스코프를 보장하는 **CSS Modules**, 혹은 타입 안정성을 지니면서도 런타임 오버헤드가 0인 **vanilla-extract**를 선택하는 것이 현재 권장되는 방식입니다 [2, 3]. * 페이지 라우터(Pages Router)에서 작동하던 기존 styled-components 프로젝트를 App Router로 마이그레이션 할 때는 이와 같은 새로운 CSS 접근 방식으로의 전환 계획이 필요합니다 [3]. * **유지보수 가능한 폴더 구조 ([[Feature-Driven Architecture|Feature-Driven Architecture]])** * App Router 사용 시 흔히 하는 가장 큰 실수는 컴포넌트, 훅, 비즈니스 로직을 `app/` 디렉토리에 라우트와 함께 전부 몰아넣는 것입니다 [4]. 프로젝트가 커지면 이는 관리 불가능한 상태가 됩니다 [4]. * `app/` 폴더 내의 파일(예: `page.tsx`, `layout.tsx`)은 오로지 라우팅 및 레이아웃 처리만을 위해 최대한 가볍게 유지해야 합니다 [5, 7]. * 실제 비즈니스 로직은 `src/features/` 내에 도메인이나 기능 단위(예: `market-data`, `user-profile`)로 묶어 분리해야 합니다 [4, 5, 7, 8]. 이렇게 하면 데이터를 불러오는 작업과 UI 표현을 깨끗하게 분리할 수 있으며, 버그 발생 시 거대한 전역 폴더를 뒤질 필요 없이 특정 기능 폴더 내부만 확인하면 되므로 유지보수가 훨씬 쉬워집니다 [5, 9]. * **실무 팁 및 표준화 설정** * 프로젝트 초기화 시 `src/` 디렉토리를 사용하여 `tailwind.config.ts` 등 설정 파일과 소스 코드를 분리하는 것이 좋습니다 [10]. * 깔끔한 코드 작성을 위해 `tsconfig.json`에서 절대 경로(`@/components/...`)를 설정하여 수많은 상대 경로(`../../../`) 작성을 방지해야 합니다 [7, 10, 11]. * API 호출을 기능별로 중앙 집중화하고 공유 폴더의 컴포넌트를 재사용하는 등 계층을 나누면 확장 및 리팩토링 시 안전성이 매우 높아집니다 [7, 8]. --- * **React [[Server Components|Server Components]](RSC)와의 호환성 한계** [[Next.js|Next.js]] App Router 환경은 브라우저가 아닌 서버에서 실행되어 HTML을 스트리밍하는 React Server Components(RSC)를 활용합니다 [2]. styled-components나 Emotion과 같은 기존의 컨텍스트 기반 런타임 CSS-in-JS 라이브러리들은 서버 컴포넌트에 React 컨텍스트가 존재하지 않기 때문에 근본적으로 호환되지 않으며, 이 환경에서는 런타임 CSS-in-JS의 사용이 문제(problematic)가 됩니다 [1, 2]. * **App Router 환경에 권장되는 스타일링 전략** 새로운 Next.js App Router 프로젝트를 구축하거나 기존 프로젝트를 App Router로 마이그레이션할 때는 런타임 CSS-in-JS를 피해야 합니다 [3]. 대신 다음의 세 가지 접근 방식 중 하나를 채택하는 것이 권장됩니다 [2, 3]. * **Tailwind CSS**: 런타임 오버헤드가 전혀 없으며, 중소규모 앱에서 컴포넌트 원시 요소(예: shadcn/ui)와 결합하여 사용하기에 적합합니다 [3, 5]. * **CSS Modules**: 복잡한 애니메이션을 구현하거나 CSS 기술 역량이 강한 팀에게 적합하며 런타임 비용이 발생하지 않습니다 [3, 5]. * **Zero-runtime CSS-in-JS (vanilla-extract)**: 빌드 타임에 정적 CSS를 생성하여 RSC와 호환되며, 여러 테마를 가진 대규모 디자인 시스템에서 타입 안전성을 확보하며 스타일링하기에 가장 적합합니다 [3, 5]. * **확장 가능한 컴포넌트 폴더 구조 설계** App Router 환경에서 컴포넌트와 스타일을 유지보수 가능하게 관리하려면, `app/` 디렉토리에 라우트, 컴포넌트, 훅(hooks), 로직을 모두 섞어 넣는 실수를 피해야 합니다 [4]. `app/` 폴더는 라우팅과 레이아웃 관리에만 엄격히 사용하고, 실제 스타일이 적용된 UI 컴포넌트와 비즈니스 로직은 `src/features/`와 같은 디렉토리에 도메인별(Feature-Driven)로 분리하여 캡슐화하는 것이 장기적인 확장성에 유리합니다 [4, 6, 7]. --- * **React [[Server Components|Server Components]](RSC) 모델의 작동 방식** [[Next.js 15 App Router|Next.js 15 App Router]] 환경에서 서버 컴포넌트는 클라이언트로 JavaScript 코드를 전송하지 않으며, 서버에서 직접 데이터를 패칭하여 렌더링된 HTML만을 브라우저로 보냅니다 [2]. 반면 동적 상태 변경, 브라우저 API 접근, 이벤트 리스너가 필요한 인터랙티브 UI는 파일 최상단에 `'use client'`를 명시하여 클라이언트 컴포넌트 경계(Client Component Boundary)를 설정해야 합니다 [3]. 하이드레이션([[Hydration|Hydration]]) 프로세스는 이러한 클라이언트 컴포넌트에 대해서만 수행되어 인터랙티비티를 활성화합니다 [6]. * **스타일링 패러다임의 충돌 및 권장 사항** RSC는 서버 전용 실행 환경으로, [[React Context|React Context]]를 사용할 수 없습니다 [7, 8]. 이는 테마나 상태를 위해 Context API에 의존하는 런타임 CSS-in-JS 라이브러리([[styled-components|styled-components]], Emotion 등)가 App Router에서 기본적으로 작동하지 않는 문제를 발생시켰습니다 [4, 7, 8]. 따라서 Next.js App Router를 사용하는 최신 프로젝트에서는 런타임 오버헤드 없이 빌드 타임에 정적 CSS를 생성하는 **Tailwind CSS**, **[[CSS Modules|CSS Modules]]**, 혹은 **vanilla-extract**([[Zero-Runtime CSS-in-JS|Zero-Runtime CSS-in-JS]])의 도입이 강력히 권장됩니다 [8-10]. * **CSS-in-JS 지원 및 레지스트리 패턴** [[Next.js 15|Next.js 15]]는 런타임 CSS-in-JS 라이브러리를 사용할 수 있도록 렌더링 중 CSS 규칙을 수집하고 이를 HTML의 ``에 주입(`useServerInsertedHTML` 훅 활용)하는 **[[Style Registry|Style Registry]] 패턴**을 지원합니다 [11]. 그러나 서버와 클라이언트의 클래스명 불일치(Hydration Mismatch)를 방지하기 위한 추가 설정(예: `next.config.js` 내 컴파일러 옵션)이 요구됩니다 [12]. 최신 `styled-components` (v6.3.0 이상)의 경우, RSC 환경을 자동 감지하여 별도의 설정 없이 인라인 `