vite typescript path alias 인식 안됨 문제 해결 가이드

vite typescript path alias 인식 안됨이 필요한 상황

vite typescript path alias 인식 안됨 현상을 만났을 때 원인 파악과 즉시 적용 가능한 해결책이 필요합니다. 이 글에서 얻을 내용: 문제의 원리(타입스크립트와 번들러의 역할 분리), 대표 원인별 진단법, vite와 TypeScript 설정 예제, 실무 체크리스트, 보안·운영 주의점과 FAQ.

vite typescript path alias 인식 안됨 핵심 개념

간단히 정리하면 TypeScript의 path 매핑은 컴파일러(또는 IDE) 레벨에서 동작하고, Vite는 런타임/번들 단계에서 모듈 경로를 해석합니다. 따라서 tsconfig.json에만 경로를 추가하면 IDE와 타입 검사기는 인식하지만 Vite(또는 esbuild)에는 해당 매핑을 알려주지 않아 "vite typescript path alias 인식 안됨" 현상이 발생합니다. Vite에서는 vite.config.ts에 alias 설정을 추가하거나 플러그인을 사용해 동일한 매핑을 적용해야 합니다.

vite typescript path alias 인식 안됨 실무 예제

아래는 tsconfig.json과 vite.config.ts를 함께 설정하는 최소 예제입니다.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["src/components/*"],
      "@/utils/*": ["src/utils/*"]
    }
  }
}

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@/components': path.resolve(__dirname, 'src/components'),
      '@/utils': path.resolve(__dirname, 'src/utils')
    }
  }
})

위 예제는 가장 단순한 케이스입니다. 모노레포나 패키지 레벨에서 작업 중이라면 경로 계산을 더 신중히 해야 합니다.

vite config alias vs tsconfig paths 비교

위 표에서 보듯 두 설정은 역할이 다르며 둘 다 맞춰줘야 합니다.

추가 실무 코드: 플러그인 기반 예제 (rollup-plugin-alias 대체)

Vite에서 tsconfig.json의 paths를 자동으로 적용해 주는 플러그인을 사용하는 예시입니다.

// vite.config.ts
import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths()]
})

이 방식은 tsconfig의 paths를 단일 원천으로 유지해 중복 설정을 줄여 줍니다.

언제 쓰면 좋고 언제 피해야 할까

• 언제 쓰면 좋은가

  • 코드베이스에서 상대경로가 지나치게 길어져 가독성이 떨어질 때
  • 컴포넌트나 유틸을 공유할 때 명확한 네임스페이스로 관리하고 싶을 때
  • 모듈 이동 시 import 경로 수정 비용을 줄이고 싶을 때

• 언제 피해야 하는가

  • 작은 프로젝트(파일 수가 적고 구조가 단순한 경우)에서는 오히려 설정 복잡도가 증가
  • 여러 빌드 도구나 플랫폼(예: Node SSR, Jest, Webpack)과 호환성을 맞춰야 하는 경우 단일 경로 설정만으로는 부족할 때

실무 체크리스트

• 프로젝트 루트에 tsconfig.json의 baseUrl와 paths가 올바르게 설정되어 있는가?
• vite.config.ts 혹은 vite 플러그인에서 동일한 alias가 적용되어 있는가?
• IDE(예: VSCode)에서 경로 자동완성이 정상 동작하는가?
• 빌드(또는 dev 서버)에서 import 오류가 발생하지 않는가?
• monorepo 환경이면 각 패키지의 경로나 루트 기준이 일치하는가?
• Jest나 Storybook 등 다른 도구에도 동일한 경로 매핑을 적용했는가?

성능·보안·운영 주의점

• 성능
  • alias 자체는 런타임 성능에 큰 영향을 주지 않습니다. 다만 잘못된 alias로 인해 중복된 번들이 생성되면 번들 크기가 증가할 수 있습니다.
• 보안
  • alias로 민감한 내부 모듈을 외부에 노출하지 않도록 주의하세요. 예를 들어 빌드 설정이 잘못되어 내부 테스트 유틸이나 시크릿 파일이 번들에 포함될 수 있습니다.
• 운영
  • CI 환경에서 경로 기준이 다르면 빌드 실패가 발생할 수 있습니다. CI의 워킹 디렉터리와 로컬이 동일한지 확인하세요.
  • 모노레포 환경에서는 루트 기준(baseUrl)과 패키지별 분리 정책을 명확히 정의해야 합니다.

추가 진단 팁

1. 오류 메시지 확인: Vite/Node가 반환하는 경로 관련 에러가 어떤 파일을 찾으려 했는지 확인
2. 로그로 확인: vite dev 서버를 --debug 모드로 띄워 alias 매핑 정보를 확인
3. 경로 절대값 검사: path.resolve로 계산한 절대경로가 존재하는지 확인
4. 플러그인 충돌 점검: 다른 플러그인이 resolve를 가로채는지 확인

자주 묻는 질문

Q1: tsconfig만 설정하면 vscode에서는 작동하는데 vite에서만 안돼요. 왜인가요? A1: IDE는 tsconfig의 paths를 사용하지만 Vite는 별도 resolve 설정이 필요합니다. vite.config.ts에 alias를 추가하거나 vite-tsconfig-paths 같은 플러그인을 사용하세요.

Q2: monorepo에서 path alias를 설정하려면 어떻게 해야 하나요? A2: 각 패키지의 tsconfig 또는 루트 tsconfig에서 paths를 정의하고, Vite 설정에서는 패키지별로 alias를 분리하거나 플러그인을 사용해 루트 tsconfig를 참조하도록 구성하세요.

Q3: Jest나 Storybook도 함께 쓰는데 경로 문제가 발생합니다. 통합 관리 방법은? A3: tsconfig를 단일 소스로 유지하고 각 도구(jest.config.ts, main.js for storybook)의 moduleNameMapper 또는 resolve.alias에 동일한 매핑을 반영하세요. 또는 공통 스크립트로 매핑을 생성해 재사용하세요.

Q4: vite-tsconfig-paths 플러그인을 사용하면 단점은 없나요? A4: 장점이 많지만 플러그인 버전이나 특정 플러그인과의 충돌로 인해 예상치 못한 매핑 문제가 생길 수 있습니다. 플러그인 대신 명시적 alias를 선호할 수도 있습니다.

정리

• vite typescript path alias 인식 안됨은 tsconfig와 Vite 설정의 역할 분리에서 발생
• tsconfig의 paths는 타입/IDE용, Vite의 resolve.alias는 런타임/번들용
• vite-tsconfig-paths 같은 플러그인으로 중복 설정을 줄일 수 있음
• 실무 체크리스트로 IDE, dev 서버, CI, 기타 도구까지 검증할 것
• 보안·운영 이슈는 번들 포함 파일과 CI 경로 기준에 유의할 것