모듈 경계

공개 방식은 API 모양과 import 경험으로 고른다

export 문법은 취향 문제가 아니라, 밖에서 읽을 이름이 몇 개인지, 파일이 대표값 하나인지, 묶음으로 다뤄야 하는지를 드러내는 설계다.

공개값이 여러 개인가 함수, 타입, 상수를 나눠 가져오면 named가 기본값이다.
파일 대표값이 하나인가 컴포넌트나 factory 하나면 default를 고려한다.
이름 공간이 필요한가 공개 API 묶음이면 namespace import가 읽기 쉽다.

import 쪽에서 보이는 신호

named import { parse }처럼 이름이 고정된다.
default 가져오는 쪽이 임의 이름을 붙일 수 있다.
namespace Utils.parse()처럼 출처가 계속 보인다.
type-only 런타임 값이 아니면 import type으로 분리한다.

선택 지도

API 안정성 우선
named export

여러 공개값과 리팩터링에 강하다

예시 export const parse = ... import { parse } from "./parser"
  • 자동 완성, tree shaking, 이름 변경 추적이 명확하다.
  • 유틸, 타입, 상수처럼 공개 항목이 늘어나는 파일에 맞다.
공개 이름이 API 계약이 되므로 rename은 영향 범위를 본다.
default export

파일의 대표값 하나를 전면에 세운다

예시 export default Button import Button from "./Button"
  • React 컴포넌트, 클래스, factory처럼 대표성이 강할 때 쓴다.
  • 가져오는 이름이 달라질 수 있어 팀 규칙과 함께 운용한다.
같은 파일에서 named와 섞이면 import 규칙이 흐려질 수 있다.
namespace import

묶음 출처를 코드에 계속 남긴다

예시 import * as MathUtil from "./math" MathUtil.clamp(value)
  • 충돌하기 쉬운 이름을 출처와 함께 읽게 만든다.
  • 공개 API 묶음, SDK 표면, barrel 파일에서 유용하다.
과도한 barrel 재노출은 의존성 방향과 번들 크기를 흐릴 수 있다.

판단 매트릭스

혼용 주의
기준 named default namespace
API 표면 함수·타입·상수 여러 개를 공개한다. 파일 대표값 하나를 공개한다. 묶음 단위 공개 API를 유지한다.
읽는 쪽 경험 이름이 고정되어 검색과 자동 완성이 쉽다. 이름을 바꿔 가져올 수 있어 자유도가 높다. 접두어가 붙어 출처와 책임이 보인다.
점검 포인트 공개 이름 변경이 호출부에 미치는 범위를 본다. 임의 이름이 팀 규칙을 흐리지 않는지 본다. barrel과 재노출이 순환 의존을 만들지 않는지 본다.
검토 순서

공개값의 개수와 대표성을 먼저 고르고, 그 다음 import 가독성, type-only 경계, barrel 재노출 여부를 확인하면 모듈 API가 흔들리지 않는다.