esbuild 도입 중 발생한 const enum 런타임 오류 해결 및 빌드 속도 55배 개선

The const enum that took down our payments

Karan Mali2026년 5월 28일9분intermediate

AI 요약

Context

Linux 환경의 느린 tsc 기반 빌드 속도로 인해 개발 생산성이 저하된 상황. 빌드 최적화를 위해 esbuild를 도입했으나, TypeScript의 declare const enum 인라이닝 특성과 esbuild의 .d.ts 무시 메커니즘 사이의 불일치로 인해 프로덕션 환경에서 런타임 값 누락 및 결제 시스템 장애 발생.

Technical Solution

프로덕션 환경은 안정성이 검증된 tsc 빌드 체계를 유지하고 로컬/개발 환경에만 esbuild를 적용하는 이원화 전략 채택
declare const enum을 일반 enum으로 변환하는 esbuild 플러그인을 구현하여 런타임 객체 생성 보장
내부 NPM 패키지의 .types 모듈을 가상화하는 플러그인을 설계하여 빈 .js 파일 로드 문제 해결
가상화 플러그인을 통해 .d.ts 기반의 타입을 런타임에 존재하는 Plain Object Literal로 대체 공급
빌드 도구의 동작 차이로 인한 런타임 오류 방지를 위한 전용 문서화 및 가드레일 설정

실천 포인트

1. 빌드 도구 교체 시 `const enum`과 같은 특수 구문의 컴파일 결과물 비교 검토

2. 외부/내부 라이브러리의 `.d.ts` 의존성이 런타임 코드 생성에 영향을 주는지 확인

3. 성능 최적화 도구는 개발 환경에 우선 적용하고 프로덕션은 검증된 보수적 도구 유지

4. 빌드 파이프라인의 암묵적 변경 사항이 프로덕션에 반영되지 않도록 PR 및 머지 프로세스 강화

태그

#Const Enum #esbuild #Build Pipeline #Runtime Error #TypeScript

원문 읽기