bluemsi/2nd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e49221df535916baca8605d6146bd52ff44ab0fd
2nd/10_Wiki/Topics/Next.js_App_Router.md
T

13 KiB
Raw Blame History

category, tags, title, last_updated
category tags title last_updated
Unified
auto-consolidated
technical-documentation
Next.js App Router 프로젝트|Next.js App Router 프로젝트
2026-05-02

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

Next.js App Router 환경에서는 React Server Components(RSC)와의 호환성 문제로 인해 기존의 런타임 CSS-in-JS(예: styled-components, Emotion) 사용이 부적합합니다 [1, 2]. 대신 확장성과 유지보수성을 위해 런타임 오버헤드가 없는 Tailwind CSS, CSS Modules, 또는 vanilla-extract와 같은 Zero-Runtime CSS-in-JS의 사용이 권장됩니다 [2, 3]. 더불어 성공적인 컴포넌트 스타일링과 관리를 위해서는 라우팅 구조와 비즈니스 로직 및 UI 컴포넌트를 분리하는 기능 기반(Feature-Driven) 아키텍처의 도입이 필수적입니다 [4].

Next.js App Router는 [React Server Components|React Server Components]를 핵심 아키텍처로 도입하여 기존의 클라이언트 측 렌더링 중심의 개발 방식에서 벗어난 새로운 패러다임을 제공하는 라우팅 시스템입니다 [1]. 기본적으로 모든 컴포넌트가 서버 컴포넌트로 동작하여 서버에서 HTML을 완전히 렌더링하며, 상태 관리나 이벤트 핸들러 등 상호작용이 필요한 경우에만 'use client' 지시어를 사용해 클라이언트 컴포넌트를 분리합니다 [2, 3]. 이러한 아키텍처 변화는 애플리케이션의 성능과 보안을 향상시키지만, 기존의 상태 및 컨텍스트 기반 스타일링 접근 방식에 중대한 영향을 미칩니다 [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].

  • React [Server Components|Server Components]와의 호환성 한계 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] 모델의 작동 방식 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].

⚖️ Trade-offs & Caveats

No trade-offs available.

🔗 Knowledge Connections

Last updated: 2026-04-26

  • Related Topics: CSS Modules, Tailwind CSS, CSS-in-JS, React Server Components
  • Projects/Contexts: 신규 Next.js App Router 프로젝트 환경 설정, 기존 React 프로젝트의 App Router 마이그레이션 전략, 기능 기반 아키텍처(Feature-Driven Architecture)
  • Contradictions/Notes: 컴포넌트 상태와 프롭스(props)에 기반한 동적 스타일링에 매우 유용하게 쓰이던 styled-components와 Emotion 같은 런타임 CSS-in-JS 기술들이 과거에는 훌륭한 개발자 경험을 제공했지만, Next.js App Router라는 최신 패러다임 하에서는 RSC와의 비호환성 및 런타임 성능 비용으로 인해 권장되지 않는 기술로 전환되었다는 점이 가장 큰 대조를 이룹니다 [1, 3, 8].

Last updated: 2026-04-26

  • 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

Reference in New Issue View Git Blame Copy Permalink