문제상황

Vite와 TypeScript를 사용해서 작업하던 중, import 구문으로 모듈을 불러올 때 아래와 같은 오류가 발생했다.

문제 원인

기존에 CRA(Create React App)에서 사용하던 방식과 같이 tsconfig.json 절대경로를 설정해주었다.

{
  "compilerOptions": {
    "baseUrl": "src",
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "paths": {
    "pages/*": ["pages/*"],
    "components/*": ["components/*"],
    "util/*": ["util/*"]
  },
  "references": [{ "path": "./tsconfig.node.json" }]
}

그런데, 알고보니 Vite는 tsconfig.json의 paths 설정을 직접적으로 사용하지 않는다고 한다.

그렇기때문에 TypeScript 설정 파일에 경로 별칭을 설정했음에도 불구하고 Vite가 이를 인식하지 못한 것이고, 결과적으로 Vite 내부 경로 해석로직과 TypeScript 설정 간의 차이가 생긴 것이다.

해결방법

이 문제를 해결하기 위해 다음과 같은 단계를 거쳤다.

Vite 설정 파일 수정

vite.config.ts파일에서 경로 별칭을 명시적으로 설정함으로써 문제를 해결할 수 있었다.

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      // `src` 디렉토리를 기준으로 각 경로 별칭 정의
      pages: "/src/pages", 
      components: "/src/components",
      // 여기에 필요한 추가 경로 별칭을 설정할 수 있다
    },
  },
});

• 참고로 경로 별칭을 설정할 때는 /src/pages와 같이 경로 앞에 /를 붙여야 한다.

이 설정을 통해 Vite는 내부적으로 제공하는 자체 경로 해석 로직에 따라 별칭을 올바르게 해석할 수 있게 된다.