Antigravity Agent
25 lines
4.6 KiB
Markdown
25 lines
4.6 KiB
Markdown
# [[Next.js 기반 대규모 웹 애플리케이션]]
|
|
|
|
## 📌[[ brief]] Summary
|
|
[[Next.js]] 기반 대규모 웹 애플리케이션은 비즈니스 로직과 UI를 체계적으로 분리하는 기능 및 도메인 중심(Feature-Driven/Domain-Driven)의 모듈형 아키텍처를 채택하여 장기적인 유지보수성과 확장성을 확보하는 현대적인 웹 개발 방식입니다 [1, 2]. 특히 최근의 [[Next.js App Router]] 환경에서는 [[React Server Components]](RSC)와의 호환성 문제로 인해 런타임 오버헤드가 있는 [[CSS-in-JS]] 대신 [[Tailwind CSS]], [[CSS Modules]], 또는 zero-runtime 방식의 CSS-in-JS([[vanilla-extract]] 등)와 같은 정적 스타일링 전략을 선택하는 것이 필수적입니다 [3-5]. 이러한 구조와 스타일링 접근은 팀 간의 협업을 돕고 기술 부채를 최소화하여, 대규모 프로젝트에서도 "예쁘게"가 아닌 "유지보수 가능한" 시스템을 구축할 수 있게 합니다 [1, 5, 6].
|
|
|
|
## 📖 Core Content
|
|
|
|
* **기능 및 도메인 중심 아키텍처 ([[Feature-Driven Architecture]]):**
|
|
대규모 Next.js 프로젝트가 성장함에 따라 컴포넌트, 훅, 비즈니스 로직을 파일 유형별로 단순 그룹화하거나 라우팅을 담당하는 `app/` 디렉토리에 모두 넣는 것은 관리를 불가능하게 만듭니다 [1]. 이를 해결하기 위해 실제 도메인(예: `market-data`, `user-profile`, `auth`)을 기반으로 하는 기능 중심의 폴더 구조(예: `src/features/...`)를 도입해야 합니다 [1, 2]. `app/` 디렉토리 내의 파일(page.tsx, layout.tsx 등)은 라우팅과 레이아웃 등 최소한의 역할만 수행하게 하고, 실제 비즈니스 로직과 UI 컴포넌트는 `features/` 하위로 위임하여 코드를 캡슐화합니다 [2, 7].
|
|
|
|
* **Next.js App Router와 CSS 아키텍처 전략:**
|
|
대규모 Next.js 애플리케이션, 특히 App Router를 사용하는 프로젝트에서 기존의 CSS-in-JS([[styled-components]], Emotion 등)는 브라우저에서 런타임에 CSS를 생성하여 성능을 저하시킬 뿐만 아니라, React [[Server Components]](RSC)에는 Context가 존재하지 않아 본질적으로 호환되지 않는 문제를 발생시킵니다 [3, 4]. 따라서 2025년 기준 대규모 프로젝트에서는 런타임 비용이 없는 Tailwind CSS나 CSS Modules를 사용하거나, 빌드 타임에 정적 CSS를 생성하는 `vanilla-extract`를 사용하는 것이 권장됩니다 [4, 5, 8]. 특히 다중 테마가 필요한 대규모 디자인 시스템에서는 런타임 오버헤드 없이 타입 안정성을 제공하는 `vanilla-extract`가 가장 이상적입니다 [5].
|
|
|
|
* **유지보수성을 위한 프로젝트 구조화 규칙:**
|
|
* **디렉토리 및 경로 관리:** 초기 프로젝트 설정 시 `src/` 디렉토리를 사용하여 `tailwind.config.ts`, `next.config.mjs` 등의 루트 설정 파일과 소스 코드를 물리적으로 분리합니다 [9]. 또한, 중첩된 상대 경로(`../../../`)로 인한 혼란을 막기 위해 `@/components/...`와 같은 절대 경로 임포트(Absolute Imports)를 강제해야 합니다 [6, 9, 10].
|
|
* **관심사 분리 ([[Separation of Concerns]]):** 데이터 패칭이나 API 호출 같은 네트워크 로직은 UI 컴포넌트와 분리하여 별도의 레이어(예: `services/` 폴더)에서 관리해야 백엔드 변경이나 유지보수에 유연하게 대응할 수 있습니다 [2, 11].
|
|
* **확장성 도구 활용:** 대규모 시스템의 경우 Storybook을 통해 재사용 가능한 UI 컴포넌트 시스템을 구축하여 일관성을 높이고, 여러 앱과 공유 패키지를 효과적으로 관리하기 위해 [[Turborepo]]나 Nx와 같은 [[Monorepo]] 도구를 도입하는 것이 권장됩니다 [6, 11].
|
|
|
|
## 🔗 Knowledge Connections
|
|
- **Related Topics:** [[Feature-Driven Architecture]], [[React Server Components (RSC)]], [[Tailwind CSS]], [[CSS Modules]], [[Zero-runtime CSS-in-JS]]
|
|
- **Projects/Contexts:** Next.js App Router 기반 프로젝트 환경, 대규모 엔터프라이즈 프론트엔드 시스템
|
|
- **Contradictions/Notes:** 소스에 따르면, 과거에는 동적 스타일링과 테마 적용의 이점 때문에 CSS-in-JS(styled-components, Emotion 등)가 널리 사용되었으나, 최근 Next.js의 App Router 및 RSC 환경의 도입으로 인해 컨텍스트(Context) 기반의 런타임 CSS-in-JS는 작동하지 않거나 심각한 성능 오버헤드를 유발하여 사용이 지양되고 있습니다. 그 대안으로 Tailwind CSS나 CSS Modules 같은 정적 렌더링 호환 스타일링 방식이 새로운 표준으로 자리 잡았습니다 [3-5].
|
|
|
|
---
|
|
*Last updated: 2026-04-26* |