공통 라이브러리 빌드 도구 교체: tsc에서 tsup으로

1. tsup 도입 이유

현재 저희 프로젝트는 @plum/shared-interfaces와 같은 공통 라이브러리를 사용하고 있으며, 기존에는 tsc를 이용해 빌드를 진행해 왔습니다. 하지만 프로젝트 규모가 커지면서 다음과 같은 실질적인 문제들을 마주하게 되었습니다.

• 환경 파편화 이슈: 라이브러리를 가져다 쓰는 프로젝트마다 환경(CJS, ESM)이 달라 "모듈을 찾을 수 없음" 혹은 ERR_REQUIRE_ESM 에러가 빈번하게 발생했습니다.
• 복잡한 설정 관리: CJS와 ESM을 동시에 지원하려면 tsconfig 파일을 여러 개 관리해야 하는 운영 리소스가 발생했습니다. 설정 하나를 바꿀 때마다 여러 파일을 신경 써야 하는 점이 번거로웠습니다.
• 느린 피드백: 인터페이스 수정 시 빌드 속도가 느려 전체적인 개발 흐름이 끊기는 기분이 들었습니다.

2. tsup이란?

tsup은 TypeScript 프로젝트를 가장 빠르고 간편하게 번들링하기 위해 만들어진 도구입니다. 단순히 파일을 옮기는 수준을 넘어, 배포 가능한 최적의 상태로 코드를 가공해 줍니다. 제가 tsup을 선택하며 주목한 특징은 다음과 같습니다.

• esbuild 기반의 압도적 속도: 내부적으로 Go 언어로 작성된 esbuild를 사용합니다. tsc처럼 자바스크립트 엔진 위에서 돌아가는 것이 아니라 네이티브 코드로 실행되기 때문에, 수백 개의 파일을 번들링할 때도 수 초 내에 작업을 마칩니다.
• Zero Config 지향: 복잡한 webpack이나 rollup 설정 없이도, 파일 경로만 지정하면 즉시 운영 환경에 적합한 빌드 결과물을 만들어 줍니다.
• TypeScript First: 이름에서 알 수 있듯 TypeScript를 기본으로 지원합니다. 별도의 로더 설치 없이도 .ts, .tsx 파일을 바로 인식하며, 빌드 과정에서 타입 정의 파일(.d.ts)까지 한 번에 생성해 줍니다.
• 번들링과 컴파일의 조화: 소스 코드를 단순히 자바스크립트로 바꾸는 것에 그치지 않고, 여러 파일을 하나로 합치고 최적화하는 과정을 알아서 처리해 줍니다.

3. 도입 시 얻는 이점

3.1. 하이브리드 모듈 지원

기존 tsc는 한 번에 하나의 모듈 형식만 출력할 수 있었지만, tsup은 --format cjs,esm 옵션 하나로 두 버전을 동시에 생성해 줍니다. 덕분에 사용하는 쪽이 구형 Node.js(CJS)든 최신 Vite/Next.js(ESM)든 상관없이 "설치하면 바로 작동"하는 라이브러리를 만들 수 있게 되었습니다.

3.2. 성능 및 개발 경험 향상

Go 언어로 작성된 esbuild를 사용하기 때문에 tsc 대비 속도가 압도적으로 빠릅니다. 특히 watch 모드 사용 시 소스 수정 사항이 즉시 반영되어 개발 흐름이 매우 매끄러워졌습니다.

3.3. 타입 정의 파일(d.ts) 번들링

기존에는 수많은 .d.ts 파일이 생성되어 라이브러리 구조가 불필요하게 노출되고 복잡해 보였습니다. tsup은 여러 개의 타입 파일을 하나(index.d.ts)로 합쳐주는 DTS Rolling 기능을 제공하여, 사용하는 입장에서 타입을 참조할 때 훨씬 깔끔하고 속도도 빨라졌습니다.

3.4. 트리 쉐이킹 & 미니파이

사용하지 않는 코드를 제거하고 결과물을 압축해 줍니다. 결과적으로 공유 라이브러리를 사용하는 메인 서비스의 최종 번들 크기를 줄이는 데 도움을 줍니다.

4. 도입 후 변화된 워크플로우

5. 적용 방법

도입 과정은 매우 간단했습니다. 기존 tsc 의존성을 유지하면서 빌드 스크립트만 아래와 같이 변경하여 적용했습니다.

# 설치
npm install tsup -D

# 빌드 실행
npx tsup src/index.ts --format cjs,esm --dts --clean

6. 참고 문서

• tsup 공식 문서
• 라이브러리 번들링 개선 과정