Yarn Monorepo 환경에서 vite-tsconfig-paths 경로 해석 문제 해결(feat. AI)
배경 및 문제 상황
Yarn Monorepo 환경에서 vite-tsconfig-paths 라이브러리를 사용해 TypeScript의 Path Alias를 Vite의 Alias로 동기화하는 설정을 진행했다.
TypeScript(LSP), Vite(Bundler), Yarn(Package Manager)의 역할 분담과 PnP 환경에 대한 이해를 바탕으로 프로젝트 설정을 구성했으나, 로컬 서버 실행 시 Yarn이 모노레포의 다른 패키지를 로드할 때, tsconfig에 설정한 path alias가 아닌 PnP virtual path에서 모노레포 패키지를 찾으려고 시도하는 오류가 발생했다. 내가 늘상 하던 일이 신규 프로젝트 설정이었고, 이번 프로젝트 설정에서도 새로운 시도는 하지 않았기에 몹시 당황스러웠다.
접근 과정
- AI 기반 디버깅 (실패): 초기 이틀간 AI(oh-my-opencode의 여러 agent들)에게 이 문제를 맡겼다. AI는 TypeScript, Yarn, Vite의 상호작용 및 설정의 깊은 부분까지 파고들었으나 해결책을 찾지 못했다.
- 인간 개발자의 디버깅 (성공): AI의 도움을 배제하고
vite-tsconfig-paths공식 문서를 재검토했다. 라이브러리가 Vite의 설정을 어떻게 변경하는지 확인하기 위해 디버깅 전용 CLI 옵션을 활성화하여 로그를 분석했다.
원인 분석
문제의 원인은 vite-tsconfig-paths의 설정 파일 인식 범위에 있었다.
- 라이브러리 동작:
vite-tsconfig-paths는 기본적으로 루트의tsconfig.json파일에 명시된paths설정만을 읽어와 Vite에 주입한다. - 프로젝트 설정: 해당 Monorepo 프로젝트는 설정을 세분화하여
tsconfig.base.json과tsconfig.app.json으로 나누어 관리하고 있었다. 이건 vite 기본 프로젝트 설정이지만 나는 평소 쓸데없는 짓이라 생각하고 지워버리던 설정이었다… - 결과: 라이브러리가 분리된 설정 파일(
tsconfig.app.json,tsconfig.base.json등)에 명시된 Path Alias를 인식하지 못해, Vite가 경로를 해석하지 못했고 이것이 Yarn PnP 해석 오류로 이어졌다.
해결
vite-tsconfig-paths 플러그인 설정 시, projects 옵션을 사용하여 명시적으로 참조할 tsconfig 파일들의 경로를 지정하거나, 엔트리가 되는 tsconfig.json이 올바른 path 설정을 포함하도록 구조를 변경하여 문제를 해결했다.
고찰: AI와 숙련된 개발자의 역할
이번 디버깅 경험은 복잡한 환경 설정 문제에서 AI의 한계와 개발자의 역할을 다시금 확인시켜 주었다.
AI의 장점은
- AI는 보편적인 설정 오류나 코드 문법에 강하다.
- 다른 오픈소스 프로젝트의 레포지토리를 검색하여 best practice를 찾는 작업도 빠르다.
- typescript, yarn, vite에 대한 깊은 지식을 학습하고 탐구하는 능력이 뛰어나다. 나도 이번 기회에 AI의 작업을 구경하며 많이 배웠다.
AI의 단점은
- 특정 라이브러리의 묵시적인 기본값(Default Behavior)이나 프로젝트의 특수한 파일 구조(Split Configs)가 결합된 ‘희귀한 컨텍스트’를 파악하는 데는 한계를 보였다.
- 디버깅 노하우(!)가 부족하다
결국 문서를 정독하고 디버깅 툴을 활용해 로우 레벨의 동작을 검증하는 기본적인 엔지니어링 역량이 문제 해결의 열쇠였다.
1줄 요약
공식 문서를 잘 읽자.
EOD
20260202
Leave a comment