--- id: wiki-2026-0508-frontend-architecture-and-folder title: Frontend Architecture and Folder Structure category: 10_Wiki/Topics status: verified canonical_id: self aliases: [Project Structure, Folder Convention, Frontend Layout] duplicate_of: none source_trust_level: A confidence_score: 0.9 verification_status: applied tags: [frontend, architecture, project-structure, conventions] raw_sources: [] last_reinforced: 2026-05-10 github_commit: pending tech_stack: language: TypeScript framework: React --- # Frontend Architecture and Folder Structure ## 매 한 줄 > **"매 file layout 의 의 architecture 의 — folder 의 dependency direction 의 enforce"**. 2026 의 의 매 dominant convention 의 **Feature-Sliced Design (FSD)** + **colocation by route** (Next.js App Router). 매 monorepo 의 의 매 cross-package boundary 의 의 nx/turbo 의 의 enforce. ## 매 핵심 ### 매 layered approach (FSD) - **app**: 의 entrypoint, provider, router setup. - **pages / routes**: 의 page-level composition. - **widgets**: 의 self-contained UI block (Header, Sidebar). - **features**: 의 user action (LoginForm, AddToCart). - **entities**: 의 domain object (User, Product). - **shared**: 의 reusable utility (UI kit, lib, config). 매 dependency 의 down-only — 의 widget 의 entity/shared 의 import 의 OK, 의 reverse 의 X. ### 매 colocation 의 rule - 의 component 의 의 close 의 의 use site. - 의 test, story, type 의 의 same folder. - Route folder 의 의 page-only 의 keep — 의 reusable 의 의 lift up. ### 매 응용 1. Solo project 의 의 minimal (`src/components`, `src/pages`). 2. Team project 의 의 FSD layered. 3. Monorepo 의 의 nx/turbo 의 의 boundary enforce. 4. Design system 의 의 separate package. ## 💻 패턴 ### FSD layout ``` src/ app/ providers/ routes/ main.tsx pages/ home/ profile/ widgets/ header/ sidebar/ features/ auth-login/ ui/ model/ api/ index.ts entities/ user/ ui/ model/ api/ shared/ ui/ lib/ config/ api/ ``` ### Next.js App Router 의 colocation ``` app/ layout.tsx page.tsx (marketing)/ # route group pricing/ page.tsx _components/ PricingCard.tsx dashboard/ layout.tsx page.tsx [id]/ page.tsx loading.tsx error.tsx _lib/ fetch-data.ts components/ # shared, lifted ui/ lib/ utils.ts ``` ### Public API per slice (`index.ts`) ```ts // features/auth-login/index.ts export { LoginForm } from "./ui/LoginForm"; export { useLogin } from "./model/use-login"; // 매 internal helper 의 의 of export 의 X — barrier. ``` ```ts // widgets/header/Header.tsx import { LoginForm } from "@/features/auth-login"; // OK — public API // import { internalHelper } from "@/features/auth-login/lib/internal"; // X ``` ### TS path alias ```jsonc // tsconfig.json { "compilerOptions": { "baseUrl": ".", "paths": { "@app/*": ["src/app/*"], "@pages/*": ["src/pages/*"], "@widgets/*": ["src/widgets/*"], "@features/*": ["src/features/*"], "@entities/*": ["src/entities/*"], "@shared/*": ["src/shared/*"] } } } ``` ### ESLint boundaries ```js // eslint.config.js import boundaries from "eslint-plugin-boundaries"; export default [{ plugins: { boundaries }, settings: { "boundaries/elements": [ { type: "app", pattern: "src/app/*" }, { type: "pages", pattern: "src/pages/*" }, { type: "widgets", pattern: "src/widgets/*" }, { type: "features", pattern: "src/features/*" }, { type: "entities", pattern: "src/entities/*" }, { type: "shared", pattern: "src/shared/*" }, ], }, rules: { "boundaries/element-types": ["error", { default: "disallow", rules: [ { from: "app", allow: ["pages", "widgets", "features", "entities", "shared"] }, { from: "pages", allow: ["widgets", "features", "entities", "shared"] }, { from: "widgets", allow: ["features", "entities", "shared"] }, { from: "features", allow: ["entities", "shared"] }, { from: "entities", allow: ["shared"] }, { from: "shared", allow: ["shared"] }, ], }], }, }]; ``` ### Slice 의 internal layer ``` features/auth-login/ ui/ # React component LoginForm.tsx LoginForm.test.tsx LoginForm.stories.tsx model/ # state, hooks, business logic use-login.ts login-store.ts api/ # network call login-request.ts lib/ # helpers (private) validate-credentials.ts index.ts # public API ``` ### Monorepo (turbo) ``` apps/ web/ # Next.js app mobile/ # React Native packages/ ui/ # design system api-client/ # tRPC/REST client config-eslint/ config-tsconfig/ ``` ```jsonc // turbo.json { "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] }, "lint": {}, "test": { "dependsOn": ["^build"] } } } ``` ### Barrel file 의 caution ```ts // 매 export * 의 의 tree-shaking 의 hurt 의 가능 export * from "./Button"; export * from "./Card"; // 매 explicit re-export 의 더 의 safe export { Button } from "./Button"; export { Card } from "./Card"; ``` ## 매 결정 기준 | 상황 | Approach | |---|---| | Solo / prototype | `src/{components,pages,lib}` flat | | Team < 5, single app | FSD-lite (skip `entities`, merge `widgets`) | | Team > 5 | Full FSD + ESLint boundaries | | Multi-app | Monorepo (turbo / nx) + shared `packages/ui` | | Next.js App Router | Route colocation + `_private` folders | **기본값**: FSD-lite (app/pages/features/shared) + path alias + ESLint boundaries. ## 🔗 Graph - 부모: [[Software Architecture]] · [[Project Structure]] - 변형: [[Feature-Sliced Design]] · [[Atomic Design]] · [[Clean Architecture]] ## 🤖 LLM 활용 **언제**: new project 의 scaffold, legacy reorg, monorepo migration, dependency direction 의 enforce. **언제 X**: 의 매 < 50 file project — flat structure 의 충분. ## ❌ 안티패턴 - **`src/components/` god folder**: 매 1000+ file 의 의 unscalable. - **Cross-feature import**: feature-A 의 feature-B 의 internal 의 reach — 의 shared/entities 의 의 lift up. - **Deep nesting** (`a/b/c/d/e/f/`): 매 navigate 의 hard — 매 max 4-level 의 keep. - **Barrel `export *`**: 매 tree-shake 의 의 break, 매 circular 의 의 hide. - **No boundary enforcement**: convention 의 의 의 only — 의 violation 의 의 silent 의 accumulate. ## 🧪 검증 / 중복 - Verified (Feature-Sliced Design docs, Next.js App Router, Vercel monorepo guide, nx docs, eslint-plugin-boundaries). - 신뢰도 A. ## 🕓 Changelog | 날짜 | 변경 | |---|---| | 2026-05-08 | Phase 1 | | 2026-05-10 | Manual cleanup — FSD layout + ESLint boundaries + monorepo 추가 |