Next.js 배럴(Barrel) 파일 가이드 (14+)

대규모 Next.js 프로젝트에서 components/**/index.ts 같은 배럴(Barrel) 파일은 거의 반사적으로 등장합니다. 임포트를 깔끔하게 만들고 폴더의 Public API를 정리할 수 있기 때문이죠. 다만 배럴을 과하게 쓰면 번들 최적화(트리 셰이킹)나 유지보수 측면에서 발목을 잡기도 합니다. 이 글은 한국 실무 기준으로 “언제 배럴을 쓰고, 어디서 멈춰야 하는지”를 정리한 가이드입니다.

---

TL;DR (요약)

• 배럴은 ‘도메인 상위 1단’까지만 두고, 더 하위 폴더는 직접 import가 기본.
• 경로 문제는 배럴 남발 대신 @/ 경로 별칭으로 해결.
• export type { ... } 타입 재수출은 안전(런타임 번들에 미포함).
• export * 와일드카드 재수출은 최소화. 필요한 것만 명시적으로 export.
• 외부 라이브러리(패키지) 최적화는 optimizePackageImports로, 로컬 배럴과는 별개.

---

배럴(Barrel) 한 줄 정의

배럴 = 폴더 안의 여러 모듈을 index.ts에서 모아 재수출(export) 하여, 바깥에서는 폴더 단위로 import하게 하는 패턴.

// components/foo/A.ts
export const A = () => null

// components/foo/B.ts
export const B = () => null

// components/foo/index.ts  ← 배럴 파일
export { A } from './A'
export { B } from './B'

// 사용처
import { A, B } from '@/components/foo'

장점

• 임포트 간결화: 여러 컴포넌트를 한 번에 가져올 수 있음
• Public API 통제: 외부에 공개할 것만 선별적으로 export
• 리팩토링 내성: 내부 파일명/경로가 바뀌어도 외부 import 경로는 유지

단점

• 과다 재수출 시 트리 셰이킹 저하: 불필요 코드가 번들에 딸려올 위험
• 탐색 비용 증가: “이게 어디서 export됐더라?”를 추적해야 함
• 관리 포인트 증가: 하위 폴더까지 촘촘히 배럴을 두면 유지보수 피곤

---

Next.js 14+ 기준 권장 전략

1) “도메인 상위 1단 배럴” 원칙

도메인(예: dashboard, profile) 상위 폴더에만 배럴을 두고, 그 아래의 세부 폴더(widgets, buttons, cards 등)는 필요할 때만 예외적으로 배럴을 둡니다.

components/
  dashboard/
    widgets/
      TokenMetric.widget.tsx
      AverageUsage.widget.tsx
      CompanyUsageChart.widget.tsx
      TopUsers.widget.tsx
      DepartmentUsage.widget.tsx
    index.ts        // ✅ 도메인 대표 API(여기까지만 배럴)
  profile/
    Avatar.tsx
    Bio.tsx
    index.ts        // ✅ 도메인별 한 장

페이지/피처에서 사용

import { TokenMetricWidget, CompanyUsageChartWidget } from '@/components/dashboard'

도메인 배럴 예시(components/dashboard/index.ts)

export { TokenMetricWidget } from './widgets/TokenMetric.widget'
export { AverageUsageWidget } from './widgets/AverageUsage.widget'
export { CompanyUsageChartWidget } from './widgets/CompanyUsageChart.widget'
export { TopUsersWidget } from './widgets/TopUsers.widget'
export { DepartmentUsageWidget } from './widgets/DepartmentUsage.widget'

// 타입은 런타임에서 제거되므로 재수출해도 번들에 영향 없음
export type {
  BaseWidgetProps,
  UserData,
  DepartmentData,
  ChartData,
} from '@/types/admin-dashboard-widget'

2) 경로 문제는 배럴 남발 대신 ‘경로 별칭’으로

../../../ 지옥은 배럴이 아니라 절대 경로/별칭으로 해결하는 게 정석입니다.

tsconfig.json 설정 예시

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

이제 어디서든 @/components/...처럼 간단히 임포트할 수 있습니다.

3) 타입 재수출은 마음 편히

export type { ... }는 자바스크립트 출력 시 제거되므로 번들 크기에 영향이 거의 없습니다. 타입 모듈을 배럴에 모아두면 DX가 좋아집니다.

4) export *(와일드카드) 최소화

와일드카드 재수출은 사용 여부를 번들러가 추적하기 까다로워질 수 있습니다. 필요한 것만 명시적으로 export하세요.

---

FAQ

Q1. 배럴을 쓰면 트리 셰이킹이 항상 깨지나요?

• 아닙니다. 다만 와일드카드 재수출이나 다단 배럴 체인은 번들러가 사용 여부를 정밀 추적하기 어렵게 만들 수 있습니다. 그래서 최소·명시적 배럴을 권장합니다.

Q2. 타입만 재수출하는 배럴은 괜찮나요?

• 예. 타입은 JS 출력에서 제거되므로 번들 크기에 영향이 없습니다.

---

결론

• 경로를 예쁘게 만들고 싶다면 배럴 남발이 아니라 경로 별칭을 먼저 적용하세요.
• 배럴은 도메인 상위 1단에만 두고, 그 아래는 직접 import로 명시성을 지키는 게 Next.js 14+ 실전에서 가장 안전합니다.
• 타입은 마음 편히 재수출, export *는 최소화. 외부 라이브러리는 별도의 패키지 최적화 옵션으로 다룹니다.