TIL 폴더 배럴 패턴과 구조적 설계의 중요성

[sgoldenbird]

📌 배운 내용 요약

• 배럴파일 방식
• re-export 문법(ESM)
  • 2-step re-export (Explicit import-export)
  • Direct re-export

---

🔍 배경 / 문제 상황

관련 데일리 스크럼

• 리액트를 사용하며 효율적인 폴더구조를 정리하던 중 각 폴더에 index.js를 두고 이 index파일을 배럴로 사용하는 방식을 알게 됐습니다.
• 팀원들과 상의를 통해 import할 때 경로가 간단해 질 수 있기 때문에 배럴 파일 방식으로 폴더 구조를 변경하기로 했습니다.
• 그런데 두개 이상의 파일이 하나의 폴더에 들어있을 경우, 다른 파일에서 import할때 불필요한 파일까지 렌더링되는건 아닌지에 대한 의문이 있었습니다.

📁 constants/
├── 📁 api/
│   ├── base.js            # BASE_URL 등 공통 설정
│   ├── endpoints.js       # 모든 API endpoint 정의
│   └── index.js           # BASE_URL.js, ENDPOINTS.js export
├── 📁 errors/
│   ├── uiErrors.js          # 사용자가 볼 에러 메시지 상수
│   ├── consoleErrors.js          # 개발자가 콘솔로 볼 에러 메시지 상수
│   └── index.js           # UI_ERRORS.js, CONSOLE_ERRORS export
├── 📁 statusCodes/
│   ├── statusCodes.js     # HTTP 상태 코드 상수
│   └── index.js           # STATUS_CODES.js default export
└── index.js               # constants 전체 export 진입점          -> 필요 없어 보여서 제거 

예를 들어 위 폴더 구조를 보면 constants/안에 errors/가 있고 그 안에 consoleErrors.js와 uiErrors.js, index.js가 있습니다. 아래는 errors/index.js에서 다른2개의 파일을 불러오는 코드입니다.

export { default as CONSOLE_ERRORS } from './consoleErrors';
export { default as UI_ERRORS } from './uiErrors';

다른파일에서 import할때는 아래처럼 파일 경로를 error까지 쓰게 되는데 그러다보니 UI_ERRORS만 필요한 경우도 CONSOLE_ERRORS까지 가져오게되는 문제가 있었습니다.

import { UI_ERRORS } from '@/constants/error';

• 배럴 파일인 index.js에서 import, export하는 방식에 대한 통일도 필요했습니다.

2-step re-export(import하고 export)

import VoteModal from './VoteModal';

export default VoteModal;

Direct re-export

export { default as VoteModal } from './VoteModal';

---

✅ 해결 방법 또는 핵심 정리

| 개념

• 배럴 파일 방식은 여러 개의 모듈(파일)을 하나의 index.js(또는 index.ts) 파일에서 export해서, 외부에서 import할 때 경로를 간단하게 만드는 방식입니다. 배럴 파일을 사용하면 아래와 같은 장점이 있습니다.
  • 내부 폴더 구조가 바뀌어도 외부 import는 그대로 유지 가능해서 리팩토링할때 유연성이 증가합니다.
  • 여러 개발 파일을 import하는 대신 한 줄로 묶어서 import 코드가 짧아지고 가독성도 좋아집니다.
• ES Modules는 re-export 문법을 제공합니다.
  위에서 정리한 것과 같이 import 후 export하는 2-step re-export(explicit re-export)방식과 바로 export하는 Direct export 방식이 있습니다.

| 여러 파일을 index 배럴파일 하나에 담아 불필요한 렌더링이 되는 케이스

• 경로를 간단히 하기 위해 배럴파일 방식을 도입했는데 예를 들어 아래와 같이 불필요한 렌더링을 줄이려고 폴더경로를 구체화한다면 이 방식을 사용하는 의미가 없어집니다. 또한 위에 정의한 배럴 파일을 도입하는 장점들도 의미를 잃습니다.

import { UI_ERRORS } from '@/constants/errors/uiErrors';

• 결정적으로 배럴 파일에서 export 했다고 해당 모듈들이 모두 렌더링(실행)되는 건 아니었습니다.
  배럴 파일에 있어도 실제로 import한 항목만 번들에 포함되고 불필요한 항목들은 tree shaking으로 제거되기 때문에, 성능상 걱정할 필요가 없습니다. 렌더링은 빌드 이후 번들된 파일 위에서 실행되고 렌더링 할때 브라우저는 번들된 JS 파일만 실행하고 위의 예시에서는 CONSOLE_ERRORS는 아예 존재하지 않기 때문에 렌더링 대상도 아니게 됩니다.
  즉, 불필요한 파일은 번들에 포함되지 않고, 번들에 포함되지 않은 파일은 브라우저에서 실행도, 렌더링도 되지 않습니다.
  따라서 아래와 같이 사용합니다.

 import { UI_ERRORS } from '@/constants/error';

| re-export 방식

• 두 방식의 장단점은 명확합니다.
  2-step방식은 import해서 export하는 배럴 파일의 역할이 명확히 보이는 장점이 있습니다. 반면 조금 귀찮습니다.
  Direct export 방식은 하나의 코드로 간단하게 구현할 수 있어 편리합니다.
  일장일단이 있지만 우리팀은 Direct export 방식을 선택했습니다.

---

🧠 느낀점 및 생각 메모

"불필요한 렌더링이 되는 것 아닐까?" 하는 질문 하나에서 출발했지만, 이번 논의를 통해 배럴 파일의 개념과 이점을 더 명확히 이해하게 되었고, 실제 import 시 불필요한 렌더링에 대한 걱정은 tree shaking 덕분에 할 필요가 없다는 점을 확인할 수 있어 좋았습니다.
단순히 "경로를 줄이기 위해 배럴 파일을 사용한다"는 개념에서 더 나아가, 실제로 번들링/렌더링 흐름까지 살펴보며 구조적인 판단 기준을 세울 수 있어서 유익했습니다. 단순한 스타일 가이드 수준을 넘어, 우리 팀만의 기준과 근거 있는 설계가 하나씩 쌓이는 과정 같아서 의미 있었습니다.

[yuj2n]

멘토님께서 알려주신 폴더 구조에 대해서는 얕게 나마 이해하고 있었는데,

• 배럴파일 방식
• re-export 문법(ESM)
  • 2-step re-export (Explicit import-export)
  • Direct re-export

와 같은 개념으로 불리는 지는 모르고 있었는데 처음 알게 되었어요!💡

또한 결정적으로 배럴 파일에서 export 했다고 해당 모듈들이 모두 렌더링(실행)되는 건 아니고
배럴 파일에 있어도 실제로 import한 항목만 번들에 포함되고 불필요한 항목들은 tree shaking으로 제거되기 때문에, 성능상 걱정할 필요가 없다는 것도 처음 알았네용 😮...
-> 그렇다면 확실히 배럴 파일 방식을 채용하고, 경로도 간소화해야할 것 같아요!

그리고

방식	추천 상황
✅ Direct re-export	대부분의 경우, 간결한 배럴 파일 작성
🟡 2-step re-export	이름 바꾸거나 가공해야 할 때

따라서 🟡 2-step re-export는 네이밍 충돌을 해결해야 할 때 아래와 같이 사용한다고 하네요!

import ButtonComponent from './Button';
export { ButtonComponent as Button };

---

📝결론

• 저희 프로젝트는 소규모 프로젝트이기 때문에 네이밍 충돌 문제 발생 경우가 적을 것 같아
  ✅ Direct re-export의 방식을 채용하는 것이 좋은 것 같습니다!!

[sgoldenbird]

동의합니다~
네이밍 충돌의 경우, Direct 방식으로도 as를 사용해 해결 가능합니다.
예를 들어 export default as superButton from './Button'처럼 변경해 가져올 수 있습니다.

[sgoldenbird]

📌 배운 내용 요약

위 본문 내용에 이어 추가적으로 고민했던 사항을 정리해봅니다.

---

🔍 배경 / 문제 상황

pages/error의 폴더 구조는 아래와 같습니다.

📂 pages
 └── 📂 error
     ├── 📜 index.js
     ├── 📂 notFound
     │   ├── 📜 index.js
     │   ├── 📜 NotFoundPage.jsx
     │   └── 📜 notFoundPage.styles.js
     └── 📂 serverError
         ├── 📜 index.js
         ├── 📜 ServerErrorPage.jsx
         └── 📜 serverErrorPage.styles.js

경로면에서 /error까지 가져오면 명확하면서도 간단할 것 같아 error 바로 안에 index를 생성하고 코드를 아래와 같이 작성했습니다.

export * from './notFound';
export * from './serverError';

그런데 *로 ./notFound와 ./serverError에서 export된 모든 값들을 가져오고 import 시 해당 파일에 접근하면
사용될 수 있는 가능성 때문에 트리쉐이킹이 되지 않을 수 있습니다.

즉, 예를 들어 다른파일에서 아래와 같이 하나의 함수를 import했을때
./notFound의 모든 함수는 물론, ./serverError의 모든 함수들 까지 가져오게 될 수 있습니다.

// 다른 파일에서
import { someFn } from '@/pages/error';

---

✅ 해결 방법 또는 핵심 정리

정리해보면

• export *는 전체 export를 그대로 노출하기 때문에 실제로 쓰지 않는 파일까지도 번들에 포함될 위험이 있음.
• 특히 규모가 크고 파일이 많은 프로젝트에서는, 이 방식이 트리쉐이킹 실패로 번들 사이즈 증가로 이어질 수 있음.
• 그래서 위에 말한 것처럼 notFound.js만 쓰더라도 serverError.js까지 포함되는 상황이 생길 수 있고, 이걸 방지하기 위해 기명 export가 권장됨.
• (import 할때 경로에 /notFound까지 포함 할 수 있지만 그렇게 하면 error에 배럴파일을 두는 의미가 없습니다. )

따라서 아래와 같이 변경합니다.

export { default as NotFoundPage } from './notFound';
export { default as ServerErrorPage } from './serverError';

---

🧠 느낀점 및 생각 메모

배럴 파일을 구성하는 것뿐만 아니라, 트리쉐이킹 관점에서 어떻게 export/import 구조를 설계해야 하는지까지 고민하게 되었다.
실제로 사용하는 것만 번들에 포함되도록 하기 위해선 기명 export가 더 안전하고 명확한 선택이라는 점을 체감했다.
앞으로는 기능 단위 모듈화뿐만 아니라 번들 최적화까지 고려한 구조 설계를 더 의식적으로 할 수 있을 것 같다.

---

참고

주강사님 조언

• 일반적인 경우는 위와 같지만 번들러마다 혹은 번들러 설정마다 작동 방식이 다를 수 있습니다.
• 추후 번들러 별-webpack, rollup-트리쉐이킹을 어떻게 내부적으로 처리하는지에 대해 찾아보면 심화학습까지 할 수 있습니다.

[sgoldenbird]

관련해 조금 햇갈릴 수 있는 3가지 export 방식의 차이

① export { default as 어쩌구 } from './어쩌구'

• barrel file에서 default export를 모듈명으로 다시 export할 때 주로 사용
• import { 어쩌구 } from '@/utils'; 이렇게 불러오기 가능

② export { default } from './어쩌구'

• default export를 다시 default export로 넘길 때 사용
• import 어쩌구 from '@/utils' 이렇게 불러오기 가능

③ export { 어쩌구 } from './어쩌구'

• 어쩌구가 named export인 경우에만 사용 가능

---

④ export 어쩌구 from './어쩌구'는 X 안됩니다.

• JavaScript에서는 export 문에선 반드시 { }나 default를 명시해야 합니다.

---

참고

named export: 여러개의 값을 이름 붙여서 export하는 방식 → 가져올 때도 이름을 정확히 맞춰서 import해야 한다.
default export: 하나의 값만 디폴트로 export → import할 때 이름을 자유롭게 정할 수 있다.

[sgoldenbird]

#98

[sgoldenbird]

롤업 테스트 후 알게된 사실 추가 기록합니다.

1. VITE 개발에서는 esbuild를 쓰고, 빌드에서는 Rollup을 씁니다.
2. export * from 구문은 default export는 가져오지 못합니다.
3. 배럴파일 방식을 사용했을 경우 default as 로 가져오든 { 이름 } 으로 가져오든, * 로 가져오든 모든 경우에 대해 트리쉐이킹이 됩니다.
4. 단순 콘솔도 트리쉐이킹이 됩니다.
5. 단, 사이드 이펙트가 되는 콘솔은(다른 함수를 콘솔로 찍는 다던지 하는) 트리쉐이킹이 되지 않고 번들시 같이 포함됩니다.