Files

T

Antigravity Agent 504fd5fb42 [G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00

7.0 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

title

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.

매 응용

Solo project 의 의 minimal (src/components, src/pages).
Team project 의 의 FSD layered.
Monorepo 의 의 nx/turbo 의 의 boundary enforce.
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`)

// features/auth-login/index.ts
export { LoginForm } from "./ui/LoginForm";
export { useLogin } from "./model/use-login";
// 매 internal helper 의 의 of export 의 X — barrier.

// 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

// 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

// 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/

// turbo.json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
    "lint":  {},
    "test":  { "dependsOn": ["^build"] }
  }
}

Barrel file 의 caution

// 매 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
응용: Monorepo with Turbo · Next.js App Router
Adjacent: ESLint Boundaries · TypeScript Path Aliases · Barrel Exports

🤖 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 추가

7.0 KiB Raw Blame History