- 번들러 없이 TypeScript 라이브러리를 손쉽게 ESM/CJS로 빌드하는 CLI 도구
-
Zod의 내부 빌드 툴로 출발해, 현재는 모든 TypeScript 라이브러리용 범용 툴로 공개
-
tsc(TypeScript 컴파일러) 를 활용하여, 확장자 리라이트, 듀얼 모듈 빌드, exports 자동 생성 등 번들러 없이도 프로덕션 수준 빌드 지원
-
빠른 배포·CI/CD 자동화에 적합하며, 라이브러리형 패키지(ESM/CJS 동시 배포) 구축 필요 시 강력 추천
-
타입 선언/exports/bin 자동화로 유지보수/배포 실수 예방 효과
특징 및 주요 기능
-
듀얼 모듈 빌드: ESM(.js)과 CJS(.cjs) 파일을 한 번에 생성
-
번들러/별도 설정 불필요: webpack, esbuild, rollup 등 없이 동작하며, 오직
package.json
과 tsconfig.json
만 필요
-
엔트리포인트 선언적 관리:
package.json#/zshy
에서 entrypoint, subpath, wildcard 등 직접 지정
-
exports 자동 생성: 빌드 후
package.json
의 "exports"
필드를 자동으로 최신화
-
파일 구조 자유: src/out 구조 고정 강요 없음, import 확장자도 자유롭게 사용
-
에셋 핸들링: JS 외 파일도 자동 복사
-
.tsx 지원: tsconfig에 맞춰 .js/.cjs/.mjs 등으로 변환
-
CLI 지원: bin 엔트리포인트 지정시 package.json#/bin 자동 생성
-
느릴 수 있음: tsc의 타입 체크와 변환에 집중, 빌드 속도보다는 신뢰성/정확성 중시
주요 동작 원리 및 차별점
-
TypeScript Compiler API로 확장자(.js/.cjs/.mjs) 및 import 경로 자동 리라이트
-
entrypoint마다 ESM/CJS 파일, 타입 선언(.d.ts/.d.cts) 동시 생성
-
CLI용 bin 엔트리포인트 지원: zshy가 자동으로 package.json#/bin에 경로 작성, shebang도 지원 필요
-
파일구조 자유, tsconfig의 outDir만 지정하면 됨
-
package.json#/exports는 빌드시 자동 생성 및 덮어쓰기
고급 기능 및 호환성
-
와일드카드/서브패스 지원:
./plugins/*
와 같은 경로 선언 가능, 실제 src 디렉터리 내 모든 하위 경로에 대해 자동 빌드
-
tsconfig.json 옵션 대부분 준수 (일부 모듈 관련 옵션은 CJS/ESM 빌드마다 override)
-
import 확장자 없는 코드도 허용 (
from "./utils"
등), 빌드시 확장자 자동 보정
-
React Native/legacy 환경도 flat build mode로 대응 가능(패키지 루트로 빌드 출력, exports 없이 index.js로 접근)
-
커스텀 exports condition(
sourceDialects
) 지원: source 조건 등 추가 지정 가능
경쟁 툴 대비 장점
-
tshy/tsup/tsdown 등과 달리, 별도 디렉터리/패키지 스텁 생성 없이 단일 outDir에 모든 빌드 결과 정리
-
TypeScript 공식 API 활용, Node.js/ESM/CJS/TS의 최신 표준 흐름과 호환성 극대화
-
추가 config, 번들러 필요 없이 단일 명령만으로 라이브러리급 TypeScript 패키지 배포 가능