FSD에서 배럴 파일 사용 가이드

📂 pages/
  📂 article-read/
    📂 ui/
      📄 ArticleReadPage.tsx
    📂 api/
      📄 loader.ts
      📄 action.ts
    📄 index.ts  ← 이것이 배럴 파일(Public API)

// pages/article-read/index.ts ✅ 올바른 사용법
export { ArticleReadPage } from "./ui/ArticleReadPage";
export { loader } from "./api/loader";
export { action } from "./api/action";

// pages/home/ui/HomePage.tsx
import { loadUserStatistics } from "../";// 🚨 위험: 자신의 슬라이스 index에서 import
export function HomePage() {
	// loadUserStatistics 사용
}

// pages/home/index.ts
export { HomePage } from "./ui/HomePage";// HomePage를 export
export { loadUserStatistics } from "./api/loader";// loadUserStatistics도 export

// pages/home/ui/HomePage.tsx ✅ 해결
import { loadUserStatistics } from "../api/loader";// 직접 import
export function HomePage() {
	// loadUserStatistics 사용
}

// math-utils.js
export function add(a, b) { return a + b; }
export function subtract(a, b) { return a - b; }
export function multiply(a, b) { return a * b; }
export function divide(a, b) { return a / b; }

// main.js
import { add } from './math-utils.js';
console.log(add(2, 3));

// 최종 번들에는 add 함수만 포함되고, 나머지는 제거됨 (Tree Shaking 성공)

// shared/ui/index.ts - 🚨 Tree Shaking 실패 원인
export { Button } from './button/Button';// 5KB
export { Input } from './input/Input';// 3KB
export { Modal } from './modal/Modal';// 8KB
export { Table } from './table/Table';// 15KB
export { Chart } from './chart/Chart';// 25KB (차트 라이브러리 포함)
// ... 50개 이상의 컴포넌트 (총 200KB+)

// pages/login/ui/LoginPage.tsx
import { Button } from '@/shared/ui';// Button(5KB)만 필요

// 번들러가 보는 의존성 그래프
LoginPage.tsx
  ↓ import { Button } from '@/shared/ui'
shared/ui/index.ts
  ↓ export { Button } from './button/Button'
  ↓ export { Chart } from './chart/Chart'// 이것도 평가됨!
  ↓ export { Modal } from './modal/Modal'// 이것도 평가됨!
button/Button.tsx ✅ (실제 사용)
chart/Chart.tsx ❌ (사용 안 함, 하지만 평가됨)
modal/Modal.tsx ❌ (사용 안 함, 하지만 평가됨)

// 배럴 파일 로딩 과정
// 1. shared/ui/index.ts 파일 전체가 평가됨
// 2. 모든 export 구문이 실행됨
// 3. 각 export된 모듈들이 메모리에 로드됨
// 4. 번들러가 "사용되지 않음"을 판단하기 어려워함

// 개발 환경: Webpack Dev Server
// Button만 수정해도 전체 shared/ui 모듈이 재로드됨
shared/ui/index.ts → 50개 컴포넌트 모두 재평가
  ↓
개발 서버 응답 시간: 3-5초 지연

# 배럴 파일 사용 시 (50개 컴포넌트)
✗ Development build time: 12.3s
✗ Hot reload time: 4.2s
✗ Memory usage: 850MB

# 개별 import 사용 시
✅ Development build time: 3.1s
✅ Hot reload time: 0.8s
✅ Memory usage: 320MB

// 이런 코드는 Tree Shaking이 어려움
// shared/ui/index.ts
export { Button } from './button/Button';
export { Modal } from './modal/Modal';

// Modal 컴포넌트 내부에 부수 효과가 있다면?
// modal/Modal.tsx
import './modal.css';// CSS 파일 import
import 'focus-trap';// 외부 라이브러리
// 이런 부수 효과 때문에 Tree Shaking이 보수적으로 작동

// webpack-bundle-analyzer 결과
Main Bundle:
  ├── Button (5KB) ✅ 실제 사용
  ├── Modal (8KB + focus-trap 15KB) ❌ 사용 안 함, 하지만 포함됨
  ├── Chart (25KB + d3 library 180KB) ❌ 사용 안 함, 하지만 포함됨
  └── ... 기타 컴포넌트들

총 번들 크기: 150KB → 실제 필요: 5KB (30배 차이!)

// shared/ui/index.ts
export { Button } from './button/Button';
export { Input } from './input/Input';
export { Modal } from './modal/Modal';
// ... 50개 컴포넌트// 사용 시
import { Button } from '@/shared/ui';
// 모든 컴포넌트 로드 위험

// 컴포넌트별 개별 배럴 파일
// shared/ui/button/index.ts
export { Button } from './Button';

// shared/ui/input/index.ts
export { Input } from './Input';

// 사용 시
import { Button } from '@/shared/ui/button';
// Button만 정확히 로드
import { Input } from '@/shared/ui/input';
// Input만 정확히 로드

페이지 로딩 시간:
❌ 배럴 파일: 2.3s (200KB 번들)
✅ 개별 import: 0.8s (15KB 번들)

개발 환경 빌드 시간:
❌ 배럴 파일: 8.5s
✅ 개별 import: 2.1s

Tree Shaking 효율성:
❌ 배럴 파일: 30% 성공률
✅ 개별 import: 95% 성공률

// ❌ 잘못된 사용법 - wildcard export
export * from "./ui/Comment";
export * from "./model/comments";

// ✅ 명시적 export 사용
export { Comment } from "./ui/Comment";
export { commentsReducer } from "./model/comments";
export type { CommentState } from "./model/comments";

// pages/article-read/index.ts
export { ArticleReadPage } from "./ui/ArticleReadPage";
export { loader } from "./api/loader";
export { action } from "./api/action";

// app/routes/article.$slug.tsx
import { ArticleReadPage } from "pages/article-read";
export { loader, action } from "pages/article-read";
export default ArticleReadPage;

// features/article-comments/index.ts
export { ArticleComments } from "./ui/ArticleComments";
export { useArticleComments } from "./model/hooks";
export type { Comment } from "./model/types";
// 내부 구현은 노출하지 않음

// entities/song/@x/artist.ts - 아티스트에서 사용할 Song 타입
export type { Song } from "../model/song";

// entities/artist/model/artist.ts
import type { Song } from "entities/song/@x/artist";

export interface Artist {
  name: string;
  songs: Array<Song>;
}

// shared/ui/index.ts ❌
export { Button } from './button';
export { Input } from './input';
// ... 50개 컴포넌트

📂 shared/ui/
  📂 button/
    📄 index.ts → export { Button } from './Button'
  📂 input/
    📄 index.ts → export { Input } from './Input'

// ✅ 올바른 방법: 직접 import
// features/user-profile/ui/UserProfile.tsx
import { updateUser } from "../api/updateUser";// 같은 슬라이스 내 직접 import
import { Button } from "shared/ui/button";// 다른 슬라이스는 Public API 사용
// ❌ 잘못된 방법: 자신의 Public API에서 import
import { updateUser } from "../";// 순환 import 위험

// ✅ 좋은 예: 필요한 것만 명시적으로 export
export { LoginForm } from "./ui/LoginForm";
export { useLoginForm } from "./model/useLoginForm";
export type { LoginCredentials } from "./model/types";

// ❌ 나쁜 예: 모든 것을 export
export * from "./ui";
export * from "./model";
export * from "./api";

// ✅ 타입과 값을 명확히 구분
export { userApi } from "./api/userApi";
export type { User, UserCredentials } from "./model/types";
export type { UserApiResponse } from "./api/types";

# webpack-bundle-analyzer로 번들 크기 확인
npm install --save-dev webpack-bundle-analyzer

# 빌드 후 분석
npm run build
npx webpack-bundle-analyzer build/static/js/*.js

// 큰 컴포넌트는 동적 import 사용
const LazyChart = lazy(() => import('shared/ui/chart'));

// 또는 코드 스플리팅
const chartModule = await import('shared/ui/chart');
const { Chart } = chartModule;

# 배럴 파일 사용 시 (11,000개 모듈)
Development server startup: 8.5s
Hot reload time: 3.2s
Bundle size increase: 68%

# optimizePackageImports 적용 후 (3,500개 모듈)
Development server startup: 2.1s (75% 개선)
Hot reload time: 0.9s (72% 개선)
Bundle size decrease: 68% 감소

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: [
      'shared/ui',
      // 내부 라이브러리'@mui/material',
      // 외부 라이브러리'lodash',
      '@heroicons/react'
    ]
  }
}

// 개발자가 작성한 코드
import { Button, Input, Modal } from 'shared/ui';

// Next.js가 자동으로 변환 (빌드 타임)
import { Button } from 'shared/ui/button';
import { Input } from 'shared/ui/input';
import { Modal } from 'shared/ui/modal';

// SWC (Speedy Web Compiler)가 처리하는 과정
// Step 1: AST 파싱
import { Button } from 'shared/ui';
         ↓
Abstract Syntax Tree 분석

// Step 2: Import 경로 재작성
Button → shared/ui/button
Input → shared/ui/input

// Step 3: 번들링 최적화
각 컴포넌트별로 독립적인 청크 생성

// ✅ 순수한 re-export만 있는 배럴 파일
// shared/ui/index.ts
export { Button } from './button/Button';
export { Input } from './input/Input';
export { Modal } from './modal/Modal';
// 다른 로직 없음

// ❌ 부수 효과가 있는 배럴 파일
// shared/ui/index.ts
export { Button } from './button/Button';
export { Input } from './input/Input';

// 이 한 줄 때문에 전체 최적화 실패!
export const THEME_VERSION = '2.1.0';// 변수 선언
console.log('UI library loaded');// 콘솔 출력
initializeTheme(); // 함수 호출

Warning: Failed to optimize package imports for 'shared/ui'
Reason: Barrel file contains non-re-export statements
Location: shared/ui/index.ts:5:1

Suggestion: Move side effects to separate modules

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: [
// FSD 아키텍처 경로들'shared/ui',
      'shared/lib',
      'entities',
      'features',

// 외부 라이브러리들'@mui/material',
      '@mui/icons-material',
      'react-icons',
      'lodash-es'
    ]
  }
}

// ❌ 최적화 방해하는 패턴 제거
// shared/ui/index.ts (수정 전)
export { Button } from './button/Button';
export { Input } from './input/Input';
export const UI_VERSION = '1.0.0';// 이 줄 제거 필요
// ✅ 최적화 가능한 패턴
// shared/ui/index.ts (수정 후)
export { Button } from './button/Button';
export { Input } from './input/Input';
export { Modal } from './modal/Modal';

// shared/ui/constants.ts (별도 파일로 분리)
export const UI_VERSION = '1.0.0';

# 개발 서버 시작 시간 측정
time npm run dev

# 빌드 시간 측정
time npm run build

# 번들 크기 분석
npm run build && npx @next/bundle-analyzer

// 런타임에서만 검증되는 import 경로
// 타입스크립트가 컴파일 타임에 검증하지 못함
import { NonExistentComponent } from 'shared/ui';// 에러 감지 어려움

// 자동 완성과 Go to Definition 이 제대로 작동하지 않을 수 있음
import { Button } from 'shared/ui';// IDE가 실제 파일 위치를 찾기 어려움

# 컴파일 타임 변환 작업으로 인한 오버헤드
기존 빌드 시간: 45s
optimizePackageImports 사용 시: 52s (+15% 증가)

// ✅ 처음부터 올바른 구조로 설계
// 각 컴포넌트별 개별 Public API
// shared/ui/button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';

// shared/ui/input/index.ts
export { Input } from './Input';
export type { InputProps } from './Input';

// 사용 시 - 명확하고 최적화됨
import { Button } from 'shared/ui/button';
import { Input } from 'shared/ui/input';

# 모든 index.ts 파일에서 wildcard export 확인
find src -name "index.ts" -exec grep -l "export \*" {} \;

# 순환 import 가능성 있는 패턴 확인
find src -name "*.ts" -o -name "*.tsx" | xargs grep -l "from \"\.\.\/\""

# webpack-bundle-analyzer 설치 및 실행
npm install --save-dev webpack-bundle-analyzer

# Next.js 프로젝트
npm run build
npx @next/bundle-analyzer

# Create React App 프로젝트
npm run build
npx webpack-bundle-analyzer build/static/js/*.js

# 개발 서버 시작 시간 측정
time npm run dev

# Hot Module Replacement 시간 측정 (Chrome DevTools에서)
# Performance 탭 → Record → 파일 수정 후 측정

// utils/performance-monitor.ts
export const measureImportTime = async (importName: string, importFn: () => Promise<any>) => {
  const startTime = performance.now();
  const module = await importFn();
  const endTime = performance.now();

  console.log(`${importName} import time: ${endTime - startTime}ms`);
  return module;
};

// 사용 예시
const ButtonModule = await measureImportTime(
  'Button from barrel',
  () => import('shared/ui')
);

const DirectButtonModule = await measureImportTime(
  'Button direct import',
  () => import('shared/ui/button')
);