Vite에서 Path Alias 설정

코드 리뷰 중 상대 경로가 너무 복잡해지는 문제가 발생했습니다. 
../../../components/...와 형태의 경로를 계속 사용하는 것은 가독성과 유지보수 등 좋지 않아 Vite에서 Path Alias를 설정하는 방법으로 수정했습니다.

1. TypeScript에서 Path Alias 설정

먼저, tsconfig.json 파일을 통해 Path Alias를 설정할 수 있습니다. 설정 예시는 다음과 같습니다:

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@/*": ["*"],
      "@components/*": ["components/*"]
    }
  },
  "include": ["src"]
}
    

위와 같이 설정하면 src 디렉토리를 기준으로 상대 경로를 별칭으로 대체할 수 있습니다. 예를 들어, import Something from "../../../components/Something"를 import Something from "@components/Something"로 간단히 바꿀 수 있습니다.

참고: TypeScript 컴파일러는 이 설정만으로 동작하지만, Vite 빌드 시스템에서는 추가 설정이 필요합니다.

2. Vite에서 Path Alias 설정

Vite는 자체적으로 Path Alias를 지원합니다. 하지만 TypeScript 설정만으로는 동작하지 않으므로 별도의 vite.config.js 파일에서 추가 설정을 해야 합니다:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import path from "path";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: [
      { find: "@", replacement: path.resolve(__dirname, "src") },
      { find: "@components", replacement: path.resolve(__dirname, "src/components") }
    ]
  }
});
    

find는 별칭, replacement는 해당 별칭의 절대 경로를 지정합니다. TypeScript의 tsconfig.json의 paths와 동일한 별칭을 사용해야 일관성을 유지할 수 있습니다.

팁: Alias 설정을 사용할 때, 프로젝트 구조가 변경되면 설정도 업데이트해야 합니다. 유지보수를 쉽게 하려면 디렉토리 구조를 안정적으로 유지하는 것이 중요합니다.

실행 중 발생할 수 있는 문제

설정 후 아래와 같은 에러가 발생할 수 있습니다:

[vite] Internal server error: Failed to resolve import "@components/common" 
from "src/Router.tsx". Does the file exist?
    

이는 Vite가 TypeScript 설정만으로는 별칭을 해석하지 못하기 때문에 발생하는 문제입니다. 위에서 설명한 vite.config.js 설정을 적용하면 해결됩니다.

3. vite-tsconfig-paths 플러그인 사용

위 방식 대신, 더 간단하게 vite-tsconfig-paths 플러그인을 사용할 수도 있습니다. 이 플러그인은 tsconfig.json에 정의된 paths를 자동으로 Vite에 적용해 줍니다.

설정 방법

1. npm install -D vite-tsconfig-paths로 플러그인을 설치합니다.
2. 다음과 같이 Vite 설정 파일에 플러그인을 추가합니다:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import tsconfigPaths from "vite-tsconfig-paths";

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

위 방법은 설정이 간단하고 유지보수가 쉬워 추천하는 방식입니다.

4. 추가 고려 사항

Path Alias 설정 시, 아래 사항들을 고려하면 더 효율적인 프로젝트 구성이 가능합니다:

• 테스트 환경에서도 Alias가 동작하도록 jest.config.js에 별도로 설정 필요
• ESLint를 사용하는 경우 .eslintrc에 Alias를 매핑
• Webpack과 같은 다른 빌드 도구를 사용하는 경우 Alias 일치 여부 확인

특히, 다양한 도구를 사용하는 프로젝트에서는 Alias 설정이 통일되지 않으면 디버깅이 어려워질 수 있습니다.

마무리

이번 글에서는 Vite에서 Path Alias를 설정하는 방법과 관련된 다양한 기술 사항을 정리했습니다:

1. TypeScript의 tsconfig.json 설정
2. Vite의 vite.config.js에서 직접 설정
3. vite-tsconfig-paths 플러그인 활용