2nd/10_Wiki/Topics/Next.js App Router 프로젝트.md

Next.js App Router 프로젝트

📌 Brief Summary

Next.js App Router 프로젝트는 React Server Components(RSC)를 기반으로 동작하기 때문에 기존의 런타임 CSS-in-JS(예: styled-components, Emotion) 라이브러리와는 호환되지 않아 스타일링 아키텍처의 변화가 필수적입니다 [1, 2]. 실무에서 유지보수성과 확장성을 확보하기 위해 스타일링은 Tailwind CSS, CSS Modules 또는 빌드 타임 기반의 **vanilla-extract**를 사용하는 것이 권장됩니다 [2, 3]. 더불어 대규모 애플리케이션으로 확장하기 위해서는 app/ 디렉토리에 모든 코드를 넣는 대신, 라우팅과 비즈니스 로직을 분리하는 기능 주도(Feature-Driven) 형태의 모듈러 폴더 구조를 채택해야 합니다 [4, 5].

📖 Core Content

• 스타일링 전략 및 CSS 아키텍처

  • Next.js App Router는 서버에서 HTML을 스트리밍하는 **React Server Components(RSC)**를 사용하므로, 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)

  • 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].

🔗 Knowledge Connections

• Related Topics: React Server Components, Tailwind CSS, CSS Modules, vanilla-extract, Feature-Driven Architecture
• Projects/Contexts: 실무에서 CSS 관리하는 방법, 대규모 프론트엔드 프로젝트 아키텍처
• Contradictions/Notes: 기존에 Pages Router와 styled-components로 잘 작동하고 있는 프로젝트라면 굳이 마이그레이션 할 필요는 없으나, App Router로 전환하고자 할 경우 반드시 Tailwind, CSS Modules, vanilla-extract 중 하나로의 마이그레이션을 계획해야 합니다 [3].

---

Last updated: 2026-04-26