TypeScript 5.7의 Path Rewriting과 모노레포 빌드 개선

문제 상황

회사 모노레포에서 패키지 간 import 경로 처리가 일관성 없이 동작하고 있었다. 특히 .ts 확장자로 import하면 개발 환경에서는 문제없지만, 빌드 후에는 .js로 변환되지 않아 런타임 에러가 발생하는 케이스가 반복됐다.

// 개발 시에는 동작
import { helper } from './utils.ts';

// 빌드 후 Node.js에서 실행 시 에러
// Error: Cannot find module './utils.ts'

기존에는 별도 스크립트로 빌드 후 경로를 일괄 변환했는데, 이 과정에서 source map이 꼬이는 문제도 있었다.

TypeScript 5.7 적용

5.7에서 추가된 --rewriteRelativeImportExtensions 플래그를 적용했다.

// tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rewriteRelativeImportExtensions": true,
    "outDir": "./dist"
  }
}

이제 소스코드에서 .ts 확장자로 작성해도 컴파일 시 자동으로 .js로 변환된다. 별도 후처리 스크립트 없이 깔끔하게 해결됐다.

모노레포 전체 적용

12개 패키지 전체에 설정을 적용하면서 몇 가지 이슈가 있었다.

• paths 매핑과 함께 사용할 때는 여전히 수동 처리 필요
• .d.ts 파일 생성 시에도 경로가 올바르게 변환되는지 확인 필요
• 기존 빌드 스크립트 제거 후 CI/CD 파이프라인 검증

전체 마이그레이션에 이틀 정도 소요됐고, 빌드 시간은 약 15% 단축됐다. 무엇보다 설정이 단순해져서 신규 패키지 추가 시 혼란이 줄어들 것으로 보인다.

결론

TypeScript가 점점 Node.js ESM 생태계와 잘 맞물려가는 느낌이다. 다만 여전히 module: "NodeNext"와 type: "module" 조합에 익숙하지 않은 팀원들이 있어서, 내부 문서 업데이트가 추가로 필요했다.