Vite기반 React 프로젝트에서 Path Aliasing 설정하기

React 프로젝트에서 Path Aliasing을 설정하면, 복잡하고 긴 상대 경로 대신 짧고 명확한 경로로 모듈을 import할 수 있습니다. 본 글에서는 Path Aliasing을 설정하는 방법에 대해 설명합니다.

 

Path Aliasing이란?

Path Aliasing은 프로젝트 내에서 특정 경로를 별칭(alias)으로 정의하여 import 할 수 있도록 하는 기능입니다.

 

예를 들어, 아래 코드와 같이 길고 복잡한 경로 대신에

import MyComponent from '../../../components/MyComponent';

 

 

다음과 같이 짧고 명확하게 코드를 작성할 수 있습니다.

import MyComponent from '@components/MyComponent';

 

Vite에서 Path Aliasing 설정하기

vite.config.ts 설정

먼저, Vite의 설정 파일인 vite.config.ts를 열어 resolve.alias 옵션에 아래와 같이 별칭을 정의합니다.

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

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@components': path.resolve(__dirname, 'src/components'),
      '@features': path.resolve(__dirname, 'src/features'),
    },
  },
});

 

위 예시에서는 @components, @features 라는 별칭(alias)으로 설정했습니다.

 

vite.config.ts 설정 파일 타입 오류

typescript에 의해 path 부분에서 타입 오류가 발생할 수 있습니다. 이때는 아래 명령어로 @types/node를 설치해주시면 됩니다.

# yarn을 사용하는 경우
yarn add @types/node

# bun을 사용하는 경우
bun add @types/node

 

TypeScript 설정(tsconfig.json)

위 vite.config 설정을 하면 JavaScript의 경우는 설정을 추가적으로 할 필요가 없지만, TypeScript의 경우에는 개발시 컴파일 오류가 발생하게 됩니다. TypeScript에서도 별칭을 올바르게 인식하기 위해 tsconfig.json 파일에 alias 경로를 설정해줘야 합니다.

 

tsconfig.app.json에 path alias 설정

tsconfig.app.json 파일을 열어 compilerOptions > paths 속성에 별칭(alias)을 추가합니다.

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

 

여기까지 하면 TypeScript 컴파일러가 별칭을 이해하고 올바르게 해석할 수 있게 됩니다.

 

Path Alias 사용하기

설정이 완료되었으니 실제 코드에서 import가 되는지 확인해봅시다.

// path alias 설정 전
import Header from '../../../components/Header';
import UserProfile from '../../../features/user/UserProfile';

// path alias 설정 후
import Header from '@components/Header';
import UserProfile from '@features/user/UserProfile';

 

 

vite-tsconfig-paths 를 사용하여 설정하기 (권장)

위와 같이 설정을 해도 되지만, vite.config 설정과 tsconfig 설정을 둘 다 해야하는 번거로움이 있습니다. 이를 해결하기 위해 vite 플러그인 중 vite-tsconfig-paths를 사용하면 tsconfig만 수정해도 vite 번들러에도 동시에 설정이 되도록할 수 있습니다.

 

우선 플러그인을 설치합니다.

# yarn 사용시
yarn add vite-tsconfig-paths

# bun 사용시
bun add vite-tsconfig-paths

 

그리고, vite.config.ts 설정 파일을 수정합니다. resolve.alias를 지우고, 플러그인을 추가하면 tsconfig로부터 alias 설정 정보를 불러와서 vite 번들러쪽에도 설정을 해줍니다.

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

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
});