Read Original
#Frontend

토스뱅크가 패키지를 관리하는 방식 #2: 토스뱅크 패키지의 세 가지 기준

토스뱅크가 패키지를 관리하는 방식 #2: 토스뱅크 패키지의 세 가지 기준
01

Summary

사전 번들링은 그만! 토스뱅크가 모노레포 패키지 관리를 정복한 3가지 기준

번들링과 문법 변환을 호스트에 위임하고 declaration sourcemap으로 디버깅 경험을 혁신한 노하우

토스뱅크 기술그룹에서 프론트엔드 패키지 개발 환경을 개선하며 수립한 '안정성, 예측 가능성, 디버깅 편의성' 중심의 3가지 패키지 배포 표준을 소개합니다. 패키지 단에서 미리 번들링 및 하위 호환 변환을 수행할 때 발생하는 Next.js App Router 지시문 문제나 코드 비대화 문제를 지적하며, 원본 구조를 유지한 채 호스트에 변환을 위임하는 명쾌한 구조적 해법을 제시합니다.

  • 01패키지 관리의 3대 축: 안정성(실행 환경 호환), 예측 가능성(의도 유지), 디버깅 편의성 구축
  • 02트랜스파일 및 번들링을 호스트 서비스에 위임하여 최신 JS 문법 최적화 및 코드 중복 최소화
  • 03Next.js App Router의 'use client' 등 파일 단위 지시문 경계를 보존하는 모듈 구조 유지 배포 전략
  • 04Declaration Sourcemap 및 원본 소스 배포를 통해 IDE 클릭 한 번으로 구현체 디버깅 가능

RECOMMENDATION

모노레포 환경에서 공통 라이브러리를 운영 중이거나 Next.js App Router 도입 후 패키지 번들링 및 디버깅 이슈로 고통받는 프론트엔드 개발자에게 강력히 추천합니다.

The Problem

패키지 사용처(호스트)에서 패키지의 브라우저 지원 범위 및 API 실행 환경 제공 여부를 별도로 확인해야 했고, 호스트에서 패키지의 원본 소스 코드를 디버깅하기 어려웠습니다.

The Solution

패키지 빌드 시 과도한 문법 변환과 사전 번들링을 피하고 원본 모듈 구조를 유지해 배포하며, 문법 변환과 최종 번들링은 호스트에 위임하고 Declaration Sourcemap을 제공하여 디버깅 편의성을 극대화했습니다.

The Result

안정성, 예측 가능성, 디버깅 편의성이라는 3가지 기준을 정립하여 패키지 제공자와 사용자의 역할을 명확히 분리하고, 빌드 도구 및 설정 결정에 일관된 판단 기준을 마련했습니다.

Trade-off

패키지 빌드는 단순화되지만 최종 번들링 및 트랜스파일링 부담이 호스트 앱으로 이동하며, 패키지 개발 단계에서 호스트의 API 및 문법 지원 여부를 엄격히 검증하는 추가적인 관리가 요구됩니다.

03

Key Concepts

Concept · 01

Declaration Sourcemap

타입 선언 파일(.d.ts)의 각 선언을 원본 TypeScript 소스 코드의 실제 위치와 연결해 주는 소스맵 파일입니다.

  • 패키지 설치 시 .d.ts.map과 원본 소스 코드를 함께 배포
  • 호스트 개발자가 IDE에서 타입 정의 대신 실제 패키지 구현 코드로 즉시 이동할 수 있도록 지원
Concept · 02

Transpilation Delegation

패키지 자체에서 구형 타겟으로 문법을 사전 변환하지 않고, 최신 문법을 유지하여 배포한 후 호스트 앱의 빌드 시점에 타겟에 맞게 변환하는 기법입니다.

  • Optional Chaining 등 최신 문법이 불필요한 헬퍼 함수로 변환되어 파일 크기가 커지는 현상 방지
  • 호스트 앱이 지원하는 정확한 브라우저 범위에 맞춰 최적의 트랜스파일링 적용
Concept · 03

Module Boundary Preservation

라이브러리 빌드 시 여러 소스 파일을 하나의 번들 파일로 합치지 않고 원본 파일 구조와 경계를 그대로 유지하며 배포하는 방식입니다.

  • Next.js App Router의 'use client' 같은 파일 단위 지시문(Directive) 경계 유지를 통해 Server/Client Component 동작 오류 방지