[Next.js] 성능 최적화 - 번들 사이즈를 줄이는 배럴 파일 관리 전략

프론트엔드 프로젝트의 규모가 커지면 우리는 자연스럽게 '깔끔한 코드'를 고민하게 됩니다. 그 과정에서 수십 개의 컴포넌트를 한곳에 모아 내보내는 배럴 파일(Barrel File) 패턴을 흔히 사용하곤 하죠. 하지만 이 편리함 뒤에는 번들 사이즈와 성능을 갉아먹는 치명적인 함정이 숨어 있습니다.
오늘은 배럴 파일이 왜 성능의 적이 되는지, 그리고 이미 커져버린 프로젝트에서 Next.js의 optimizePackageImports를 통해 어떻게 우아하게 탈출할 수 있는지 알아보겠습니다.
 
 
 

1. 배럴 파일(Barrel File)이란?

배럴 파일은 여러 모듈을 하나의 index.ts 파일로 모아서 다시 내보내는(Re-export) 방식입니다.

// components/index.ts (배럴 파일)
export { default as Button } from './Button';
export { default as Card } from './Card';
export { default as Modal } from './Modal';

 
사용하는 쪽에서는 경로가 짧아져서 보기 좋습니다.

import { Button } from '@/components'; // 깔끔!

 
 

2. 왜 배럴 파일을 지양해야 할까?

배럴 파일은 index.ts에서 여러 모듈을 export하여 경로를 단순화하는 패턴입니다. 하지만 이는 자바스크립트 엔진이 '필요하지 않은 코드까지 해석하게 만드는' 결과를 초래합니다.
 

① 의존성 그래프의 연쇄 폭발

내가 Button 하나만 사용하려고 배럴 파일을 참조하는 순간, 번들러는 해당 파일에 연결된 Card, Modal은 물론이고, 그 컴포넌트들이 사용하는 무거운 외부 라이브러리들까지 모두 메모리에 로드해야 합니다. 이는 의존성 그래프를 비정상적으로 크게 만듭니다.

② 트리 셰이킹(Tree Shaking)의 한계

React 공식 문서와 관련 생태계에서는 트리 셰이킹이 모든 상황에서 완벽하지 않음을 시사합니다. 특히 라이브러리에 sideEffects: false 설정이 누락되어 있거나 복잡한 참조가 얽혀 있다면, 번들러는 사용하지 않는 코드까지 "혹시 모르니" 번들에 포함하게 됩니다.

③ 개발 환경(HMR) 및 테스트 성능 저하

파일 하나만 수정해도 배럴 파일과 연결된 수백 개의 모듈 관계를 다시 계산해야 합니다. 이는 Fast Refresh(HMR) 속도를 늦추고, 유닛 테스트 시에도 불필요한 모듈을 로드하게 만들어 전체적인 개발 생산성을 떨어뜨립니다.
 
 
 

3. 실전 해결책: Next.js의 optimizePackageImports

가장 좋은 방법은 직접 경로(Direct Import)를 사용하는 것이지만, 이미 수만 줄의 코드가 배럴 파일을 쓰고 있다면 일일이 수정하기란 불가능에 가깝습니다. 이때 Next.js 13.5+에서 도입된 optimizePackageImports를 활용하면 됩니다.

자동 경로 변환 (Automatic Mapping)

Next.js 공식 문서에 따르면, 이 옵션은 빌드 시점에 배럴 파일을 거치지 않도록 임포트 구문을 직접 경로로 자동 재작성합니다.

• 사용자 코드: import { Button } from '@/components'
• 컴파일 후: import { Button } from '@/components/Button/Button.tsx' (자동 변환)

설정 방법 (next.config.js)

주로 아이콘 라이브러리나 자체 UI 키트처럼 모듈 개수가 많은 패키지를 등록할 때 효과가 드라마틱합니다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    // 배럴 파일 최적화가 필요한 패키지 리스트 등록
    optimizePackageImports: ['@my-project/ui', 'heavy-icons-lib'],
  },
}

module.exports = nextConfig

 
 

4. 요약 및 권장 사항

기술적 부채를 피하고 성능을 유지하기 위해 다음의 가이드를 권장합니다.

1. 가급적 직접 참조하세요: 신규 프로젝트라면 import Button from '@/components/Button'처럼 명확한 경로를 사용하는 습관을 들이는 것이 좋습니다.
2. 공식 문서의 도움을 받으세요: Next.js는 lucide-react, @mui/material 등 주요 라이브러리에 대해 이 최적화를 이미 기본으로 적용하고 있습니다. 내가 쓰는 라이브러리도 해당되는지 확인해 보세요.
3. ESLint를 활용하세요: no-restricted-imports 규칙을 설정하여 팀원들이 무분별하게 배럴 파일의 입구(index)를 참조하지 못하도록 강제할 수 있습니다.

 

5. 실전 적용 사례

이론을 넘어 실제 프로젝트에 optimizePackageImports를 적용했을 때 어떤 변화가 있는지 수치로 확인해 보겠습니다. 이번 최적화는 사내 공통 컴포넌트 라이브러리와 무거운 외부 패키지(lodash, monaco-editor 등)를 대상으로 진행했습니다.
 

적용 코드 (next.config.js)

주로 배럴 파일 구조를 가진 사내 컴포넌트 패키지와 크기가 큰 라이브러리들을 최적화 목록에 추가했습니다.
 

// next.config.js
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      '@사내컴포넌트',
      'lodash',
      'moment',
      'monaco-editor/react',
      'monaco-editor',
    ],
  },
}

최적화 결과 (First Load JS)

결과는 기대 이상이었습니다. 공통으로 로드되는 _app.js의 크기가 드라마틱하게 줄어들었습니다.

항목

최적화 전

최적화 후

절감률

 

결과 분석

• _app.js의 변화: 전역에서 참조하던 배럴 파일들이 직접 참조 방식으로 최적화되면서, 초기 로딩 시 불필요하게 포함되었던 코드들이 대거 제거되었습니다.
• 사용자 경험 개선: 공통 번들 사이즈가 289kB나 줄어들었다는 것은 모든 사용자가 첫 페이지를 진입할 때 다운로드해야 할 JS 용량이 절반 이상 가벼워졌음을 의미합니다. 체감 로딩 속도는 훨씬 빨라질 것입니다.

 

 
실제 프로젝트에 적용해 본 결과, optimizePackageImports는 단순히 이론적인 최적화가 아니었습니다. 설정 몇 줄만으로 공통 번들 사이즈를 56%나 줄인 수치가 그 효용성을 증명합니다.
그동안 배럴 파일의 편리함 때문에 성능을 포기하고 계셨나요? 아니면 거대해진 의존성 때문에 엄두를 내지 못하고 계셨나요?
이제 Next.js의 스마트한 최적화 기능을 빌려, 개발 경험(DX)과 사용자 경험(UX) 두 마리 토끼를 모두 잡아보시길 바랍니다.

 

참고 자료

• Next.js API Reference - optimizePackageImports
• Vercel Blog - How we optimized package imports in Next.js
• https://www.heropy.dev/p/pd8CoS