🚀 번들 사이즈를 죽이는 걸 멈춰라

Source: Dev.to

우리는 모두 Barrel Files(index.ts 파일, 디렉터리의 모든 것을 내보내는 파일)를 좋아합니다. 이 파일들은 우리의 import 문을 깔끔하고 정돈된 형태로 만들어 줍니다:

// 😍 Looks clean...
import { Button, Header, Footer } from './components';

하지만 그 한 줄의 코드가 CI/CD 속도를 늦추고, 번들 크기를 부풀리며, 악몽 같은 “Module is undefined” 순환 의존성 오류를 일으키고 있을 가능성이 높습니다.

이 문제를 자동으로 해결해 주는 도구를 만들었고, 오늘은 여러분과 공유하려 합니다.

---

배럴 파일의 숨겨진 비용 📉

When you import a single named export from a barrel file, many bundlers and test runners (like Jest) end up loading every other file exported in that barrel to resolve the module.

• 느린 테스트 – Jest에서 Button을 가져오면 Table, Chart, HeavyLibrary까지도 같은 index.ts를 공유한다는 이유만으로 실수로 로드될 수 있습니다.
• 트리‑쉐이킹 실패 – Webpack과 Rollup이 점점 개선되고 있지만, 깊게 중첩된 배럴 파일은 종종 프로덕션 번들에 죽은 코드를 포함하게 만듭니다.
• 순환 의존성 – 모듈 A가 인덱스를 통해 모듈 B를 가져오고, 모듈 B가 같은 인덱스를 통해 모듈 A를 가져오면 런타임 충돌이 발생합니다.

해결책: 직접 임포트 🛠️

수정은 간단하지만 번거롭습니다. 다음을 변환합니다:

import { Button } from './components';

다음과 같이:

import { Button } from './components/Button';

500개 이상의 파일을 수동으로 처리하는 것은 고통스럽습니다. 그래서 자동화했습니다.

소개: no-barrel-file

오픈‑소스 CLI 도구이자 GitHub Action으로, 프로젝트를 스캔하여 배럴 파일에 의존하는 import를 찾아 직접 경로로 자동 재작성합니다.

✨ 특징

• 자동 수정 – ts-morph(AST 변환, 정규식이 아님)를 사용해 import를 안전하게 재작성합니다.
• 스마트 – tsconfig.json의 paths와 별칭을 존중합니다.
• 유연 – npx로 실행하거나 전역 설치, CI에서도 실행할 수 있습니다.

💻 로컬에서 사용하는 3가지 방법

방법 1 – “한 번만” (설치 없이)

의존성을 설치하지 않고 프로젝트를 확인하는 가장 쉬운 방법은 npx를 사용하는 것입니다.

# Just list the barrel files
npx no-barrel-file display

# Fix the imports
npx no-barrel-file replace --alias-config-path tsconfig.json

방법 2 – “프로젝트 표준” (개발 의존성)

팀 전체가 배럴 파일을 사용하지 않도록 하려면 개발 의존성으로 설치하세요.

npm install -D no-barrel-file
# or
pnpm add -D no-barrel-file

package.json에 스크립트를 추가하세요:

{
  "scripts": {
    "fix:barrels": "no-barrel-file replace --alias-config-path tsconfig.json",
    "check:barrels": "no-barrel-file display"
  }
}

이제 팀의 누구든지 npm run fix:barrels를 실행할 수 있습니다.

방법 3 – “파워 유저” (전역 설치)

여러 저장소에서 작업하고 이 도구를 터미널 어디서든 사용하고 싶다면:

npm install -g no-barrel-file

# Now you can run it anywhere
no-barrel-file display

🤖 GitHub Actions로 자동화하기

코드 품질을 유지하는 가장 좋은 방법은 자동화하는 것입니다. 새로운 배럴 파일이 저장소에 들어오지 않도록 GitHub Action을 공개했습니다.

옵션 A – 자동 수정 모드 (권장)

이 워크플로는 풀 리퀘스트에서 지연된(import) 임포트를 감지하고 자동으로 수정한 뒤 변경 사항을 브랜치에 푸시합니다.

파일: .github/workflows/fix-barrels.yml

name: Auto-Fix Barrel Files
on: [pull_request]

permissions:
  contents: write # Required to commit changes

jobs:
  fix-imports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run No Barrel File
        uses: chintan9/no-barrel-file@v1
        with:
          mode: 'replace'
          alias-config-path: 'tsconfig.json'
          extensions: '.ts,.tsx'

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "refactor: resolve barrel file imports"

옵션 B – 감사 모드

코드를 자동으로 수정하지 않고 CI 로그에 배럴 파일 보고서만 받고 싶다면:

- name: Audit Barrel Files
  uses: chintan9/no-barrel-file@v1
  with:
    mode: 'display'
    root-path: 'src'

결과

• Jest 시작 시간: 약 30% 감소.
• 순환 의존성 오류: 완전히 사라짐.
• 번들 크기: 약간 감소 (기존 트리쉐이킹 설정에 따라 다름).

직접 사용해 보기!

여러분의 피드백을 듣고 싶어요. 시간이 절약되었다면 GitHub에 별표를 달아 주세요!

[no-barrel-file](https://www.npmjs.com/package/no-barrel-file)

🐙 **GitHub:** [github.com/chintan9/no-barrel-file](https://github.com/chintan9/no-barrel-file)

Happy coding! 🚀

코딩 즐겁게! 🚀