모듈 경계

ES 모듈의 공개 방식 선택 기준

모듈은 파일 내부 구현과 외부 사용 지점을 나누는 경계다. 어떤 방식으로 내보낼지는 API의 안정성과 읽기 쉬운 의존성에 맞춰 고른다.

API 표면 외부 계약 named default barrel 재노출 import

선택 순서

1

public API 표면 정하기

외부 파일이 써야 하는 함수, 타입, 상수만 export 목록에 남긴다.

2

named export 우선

여러 값을 내보내거나 자동 완성·tree shaking 명확성이 중요하면 named export를 기본으로 둔다.

3

대표 컴포넌트만 default

파일이 한 클래스, React 컴포넌트, factory 하나를 대표할 때만 default export를 쓴다.

4

barrel과 alias 점검

index.ts barrel, tsconfig paths, bundler alias가 순환 의존성을 만들지 않는지 확인한다.

named

리팩터링에 강하다

이름을 맞춰 가져오기 때문에 잘못된 import를 컴파일 단계에서 찾기 쉽다.

default

대표성이 필요하다

임의 이름으로 가져올 수 있어 팀 규칙이 없으면 이름이 흩어질 수 있다.

namespace

충돌 회피

유틸리티 묶음을 한 객체처럼 다룰 때 이름 공간을 분리해 읽기 쉽다.

type-only

런타임 import를 지운다

타입만 필요하면 import type과 export type으로 번들에 남는 값을 없앤다.

검토 단서

모듈 설계를 볼 때는 구현보다 export 목록, type-only 경계, barrel 재수출을 먼저 보면 의존성 방향과 공개 API가 빠르게 보인다.