프론트엔드 디자인 패턴 (6) — 폴더 구조는 의존성 규칙이다: FSD와 기계적 강제

src/
  components/
  hooks/
  utils/
  api/
  types/
  constants/

src/
  features/
    orders/     { components/, hooks/, api/, types.ts }
    users/
    reports/
  shared/

// features/orders/components/OrderRow.tsx
import { UserAvatar } from '../../users/components/UserAvatar';
import { useReportFilter } from '../../reports/hooks/useReportFilter';
 
// features/users/components/UserDetail.tsx
import { OrderHistory } from '../../orders/components/OrderHistory';   // ← 순환

// a.ts
import { b } from './b';
export const a = 'A';
export const combined = a + b;    // b가 아직 초기화 전이면 undefined
 
// b.ts
import { a } from './a';
export const b = a + 'B';         // a도 아직 초기화 전

app → pages → widgets → features → entities → shared

src/
  app/                          # 앱 초기화: 프로바이더, 라우터, 전역 스타일
    providers/
    styles/
 
  pages/                        # 라우트 단위 조립 (Next.js와 충돌 시 views/로 개명)
    dashboard/
    project-detail/
 
  widgets/                      # 여러 feature를 조합한 자족적 UI 블록
    kpi-summary-panel/
    project-progress-chart/
    header/
 
  features/                     # 사용자가 하는 '행위' — 동사
    update-kpi-target/
    export-report/
    filter-by-discipline/
    toggle-project-favorite/
 
  entities/                     # 도메인 명사 — 데이터 모델 + 그 표현
    project/
    kpi/
    discipline/
    user/
 
  shared/                       # 도메인을 모르는 것
    ui/                         # Button, Input, Modal
    lib/                        # 날짜 포맷, 숫자 포맷
    api/                        # fetch 클라이언트, 인터셉터
    config/

// entities/project/model/types.ts
export type Project = { id: string; name: string; progress: number; disciplineId: string };
 
// entities/project/api/getProject.ts
export const projectQueries = {
  detail: (id: string) => ({ queryKey: ['project', id], queryFn: () => api.get(`/projects/${id}`) }),
  list: (filter: Filter) => ({ queryKey: ['projects', filter], queryFn: () => api.get('/projects', filter) }),
};
 
// entities/project/ui/ProjectCard.tsx — 표현만, 행위는 slot으로 받는다
export function ProjectCard({ project, actions }: { project: Project; actions?: ReactNode }) {
  return (
    <article>
      <h3>{project.name}</h3>
      <ProgressBar value={project.progress} />
      <footer>{actions}</footer>      {/* ← feature가 여기 꽂힌다 */}
    </article>
  );
}

// features/toggle-project-favorite/ui/FavoriteButton.tsx
import { type Project } from '@/entities/project';       // 아래 층 참조 — OK
 
export function FavoriteButton({ project }: { project: Project }) {
  const mutation = useToggleFavorite(project.id);
  return <IconButton onClick={() => mutation.mutate()} pressed={project.isFavorite} />;
}

// widgets/project-list/ui/ProjectList.tsx
import { ProjectCard, projectQueries } from '@/entities/project';
import { FavoriteButton } from '@/features/toggle-project-favorite';
 
export function ProjectList({ filter }: { filter: Filter }) {
  const { data } = useQuery(projectQueries.list(filter));
  return (
    <ul>
      {data?.map(p => (
        <li key={p.id}>
          <ProjectCard project={p} actions={<FavoriteButton project={p} />} />
        </li>
      ))}
    </ul>
  );
}

// entities/project/index.ts
export { ProjectCard } from './ui/ProjectCard';
export { projectQueries } from './api/queries';
export type { Project } from './model/types';
// ProjectCard 내부에서 쓰는 것들은 내보내지 않는다

import { ProjectCard } from '@/entities/project';                    // ✅
import { ProjectCard } from '@/entities/project/ui/ProjectCard';     // ❌ 내부 침투

// package.json — 부수효과 없음을 선언하면 번들러가 안전하게 제거한다
{ "sideEffects": false }

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['@/entities/project', '@/shared/ui'],
  },
};

// eslint.config.js (flat config)
import boundaries from 'eslint-plugin-boundaries';
 
const LAYERS = ['app', 'pages', 'widgets', 'features', 'entities', 'shared'];
 
export default [
  {
    plugins: { boundaries },
    settings: {
      'boundaries/elements': LAYERS.map(layer => ({
        type: layer,
        pattern: `src/${layer}/*`,
        capture: ['slice'],
      })),
    },
    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'] },
        ],
      }],
 
      // 같은 레이어의 다른 슬라이스 금지 (shared 제외)
      'boundaries/no-private': ['error', { allowUncles: false }],
    },
  },
];

// eslint-plugin-import만으로
'import/no-restricted-paths': ['error', {
  zones: [
    { target: './src/shared',   from: './src/entities' },
    { target: './src/shared',   from: './src/features' },
    { target: './src/entities', from: './src/features' },
    { target: './src/entities', from: './src/widgets' },
    { target: './src/features', from: './src/widgets' },
    { target: './src/features', from: './src/pages' },
    { target: './src/widgets',  from: './src/pages' },
  ],
}],

'no-restricted-imports': ['error', {
  patterns: [
    {
      group: ['@/entities/*/*', '@/features/*/*', '@/widgets/*/*'],
      message: '슬라이스 내부를 직접 import하지 마세요. 공개 API(index.ts)를 사용하세요.',
    },
  ],
}],

// .dependency-cruiser.cjs
module.exports = {
  forbidden: [
    {
      name: 'no-circular',
      severity: 'error',
      comment: '순환 의존성은 초기화 순서 버그와 코드 분할 실패를 만듭니다.',
      from: {},
      to: { circular: true },
    },
    {
      name: 'no-orphans',
      severity: 'warn',
      comment: '아무도 참조하지 않는 모듈 — 삭제 후보입니다.',
      from: { orphan: true, pathNot: ['\\.d\\.ts$', '(^|/)app/'] },
      to: {},
    },
    {
      name: 'layers-downward-only',
      severity: 'error',
      from: { path: '^src/entities' },
      to: { path: '^src/(features|widgets|pages|app)' },
    },
  ],
  options: {
    tsConfig: { fileName: 'tsconfig.json' },
    doNotFollow: { path: 'node_modules' },
  },
};

{
  "scripts": {
    "arch:check": "depcruise src --config .dependency-cruiser.cjs",
    "arch:graph": "depcruise src --config .dependency-cruiser.cjs --output-type dot | dot -T svg > deps.svg"
  }
}

# .github/workflows/ci.yml
- name: 아키텍처 규칙 검사
  run: |
    npm run lint
    npm run arch:check

app/                          # Next.js 라우팅 전용 — 얇게 유지
  layout.tsx
  dashboard/page.tsx          # src/views/dashboard를 렌더하기만 한다
  projects/[id]/page.tsx
 
src/
  views/                      # FSD의 pages 레이어를 개명
    dashboard/
    project-detail/
  widgets/
  features/
  entities/
  shared/

// app/dashboard/page.tsx — 라우팅 어댑터일 뿐
import { DashboardPage } from '@/views/dashboard';
 
export const metadata = { title: 'KPI 대시보드' };
export default function Page() {
  return <DashboardPage />;
}

// 프론트엔드에서 이걸 그대로 하면
interface ProjectRepository { findById(id: string): Promise<Project>; }
class HttpProjectRepository implements ProjectRepository { /* ... */ }
class GetProjectUseCase {
  constructor(private repo: ProjectRepository) {}
  async execute(id: string) { return this.repo.findById(id); }
}
class ProjectDTO { static toDomain(dto: unknown): Project { /* ... */ } }

// packages/features/package.json
{
  "name": "@app/features",
  "dependencies": {
    "@app/entities": "workspace:*",
    "@app/shared": "workspace:*"
  }
}