고군분투

Vite+React+TS 프로젝트 alias경로 설정하기

S_sunny 2025. 6. 25. 22:49

프로젝트에서 다른 곳에 있는 모듈을 불러올때

상대경로를 사용해 불러오는것 보다 alias경로를 통해 불러오는 것이 가독성이 훨씬 좋다.

 

// Before
import Button from '../../../components/Button';
import { UserType } from '../../../../types/user';

// After
import Button from '@/components/Button';
import { UserType } from '@/types/user';

이렇게 긴 상대경로를 짧은 별칭으로 대체하는 기능을 Path Alias라고 하는데

이 기능을 사용하려면 프로젝트에서 별도로 설정을 해주어야 한다.

 

설정할때마다 그때그때 검색하며 세팅했더니 헷갈리는 부분도 있고 헤맸던 부분이 있어서

이번에 제대로 알아보면서 정리해보았다.

 

우선 프로젝트에서 사용하는 도구에 따라 설정방법에 조금씩 차이가 있기 때문에

vite, react, typescript를 사용하는 프로젝트를 기준으로 설정하는 방법을 정리했다.

 

 

Path Alias 설정하기 - 방법1) 직접 기재

1. Vite 설정 (vite.config.ts)

vite의 resolve.alias 옵션을 통해 alias 경로를 설정할 수 있다.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
  /* vite-alias 설정 */
    alias: [
      { find: '@', replacement: '/src' },
      { find: '@components', replacement: '/src/components' },
      { find: '@utils', replacement: '/src/utils' }
    ]
  }
});

https://ko.vite.dev/config/shared-options.html#resolve-alias

 

2. Typescript 설정 (tsconfig.app.json)

프로젝트를 실행시키면 타입스크립트 관련 파일이 tsconfig.json, tsconfig.node.json, tsconfig.app.json 이렇게 3개가 생기는데

그 중 tsconfig.app.json 파일을 수정해야한다. 

기존에 설정되어있는 내용 하단에 baseUrl과 path를 지정한다.

// tsconfig.app.json
{
  "compilerOptions": {
  // ...기존 설정들..
  /* vite-alias 설정 */
    "baseUrl": ".",
    "paths": {
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"],
      "@/*": ["./src/*"]
    }
  }
}

baseUrl 을 기준으로 paths의 경로를 읽어오기 때문에 자신의 경로에 따라 잘 맞추어서 설정해야한다.

 

3. (선택사항) VS Code 설정

경로는 연결이 되는데 자동완성이 되지 않는다면 VS Code 설정을 확인하고 "non-relative"로 설정한다.

// settings.json
{
  "typescript.preferences.importModuleSpecifier": "non-relative"
}

 

 

Path Alias 설정하기 - 방법2) 플러그인 사용

1. vite-tsconfig-paths 추가

플러그인을 설치하면 타입스크립트의 paths 설정을 읽어와서 Vite에 자동으로 적용할 수 있다.

먼저 프로젝트에 개발모드로 설치를하고,

npm install -D vite-tsconfig-paths

 

2. vite.config.ts에 플러그인을 사용을 명시한다.

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

export default defineConfig({
  /* tsconfigPaths 사용 명시 */
  plugins: [react(), tsconfigPaths()],
});

이렇게 설정해 둔 다음 tsconfig.app.json에만 한번 paths 설정을 해두면 자동으로 동기화 되어 alias 설정이 가능하기 때문에

경로설정의 번거로움도 줄어들고 오타가 생길 확률도 줄일 수 있다.

 

*하지만 나는 이번에 단계별로 제대로 확인해보기 위해 플러그인 없이 직접 설정을 했다.

 

 

내가 헤맨 부분들과 해결법

1. tsconfig.json는 수정하지 않아도 된다

구글링을 하며 본 많은 글들에서 tsconfig.json을 수정하라는 내용을 보고 설정했는데

VS Code에서 alias경로로 자동완성이 되지 않고,

alias경로를 직접 적어서 불러와도 밑줄이 생기면서 해당 선언을 찾을 수 없다고 나왔다.

tsconfig.app.json까지 수정하는 글을 보고 3개 파일에 설정하고 난 뒤에야 경로 설정이 제대로 되었는데

tsconfig.json에 원래 적혀있는 부분을 보니

"references": [
  { "path": "./tsconfig.app.json" }, 
  { "path": "./tsconfig.node.json" }
],

이렇게 tsconfig.app.json 을 참조해오고 있었다.

tsconfig.json은 마스터 설정 파일로 다른 설정 파일들을 참조만 하는 역할을 한다고 한다.  

실제 컴파일러 옵션은 각각의 개별 설정 파일에서 관리되기 때문에 이 파일에서 추가로 설정을 해줄 필요는 없었다.

 

* Vite의 빌드 프로세스에 의한 부분이라고 한다.

vite는 최적화와 관심사 분리를 위해 여러 tsconfig 파일을 사용한다.

-tsconfig.json: 전체 프로젝트의 기본 설정
-tsconfig.app.json: 브라우저/React 앱용 설정
-tsconfig.node.json: Node.js/빌드 도구용 설정
VS Code는 현재 편집 중인 파일의 위치에 따라 적절한 tsconfig 파일을 선택하는데,

src/ 폴더 내의 파일을 편집할 때는 tsconfig.app.json을 우선적으로 사용한다.

(cmd/ctrl+Shift+P > Go to Project Configuration 으로 확인해보면 tsconfig.app.json 으로 이동한다.)

참고) https://velog.io/@okko8522/Vite-씨-왜-그렇게-빌드하세요-관심사-분리와-성능-향상의-묘한-조화

 

2. path.resolve 꼭 써야하나?

이전에 내가 설정한 프로젝트에서는 vite.config.ts 파일에 path.resolve(__dirname, 'src') 없이 경로를 바로 설정해줬는데

구글링 예제들에서는 모두 path.resolve를 사용한 경로를 쓰고 있었고 그러기 위해 @types/node를 설치하는 방법이 나와있었다.

분명 경로를 바로 작성해도 alias경로를 잘 불러왔었는데 무슨차이인지 알아보니 이것도 Vite의 영향을 받고있었다.

 

웹팩을 사용할 경우 런타임에 정확한 절대경로가 필요해서 path.resolve(__dirname, 'src')로 경로를 지정해주는것이 필수였는데

Vite는 개발/빌드과정에서 내부적으로 알아서 경로처리를 하기 때문에 '/src'라고만 적어도 경로를 이해할 수 있다.

때문에  { find: '@', replacement: '/src' } 만으로도 설정이 가능하기 때문에 굳이 필요한 부분은 아니였다.

* chat gpt를 통해 알아보니 다른환경에서의 호환성과 정확성을 위해 관례적으로 사용하는 면이 있다고 한다.

 

3. @types 를 alias경로로 사용하면 안된다.

내가 제일 오랜 시간을 소비하게 만든 부분이다...

위에서 적은 모든 설정을 제대로 했는데도 @types 경로가 불러와지지 않아서 애꿎은 설정파일을 얼마나 수정했는지 모른다...ㅠ

결론은 node_modules/@types/와 충돌이 일어나기 때문에 @types는 alias 경로로 연결되지 않아서 내가 export한 모듈을

불러올 수 없는 것이였다.

@types는 패키지 네임스페이스로 인식한다는거..

// 그래서 types폴더는 보통 이렇게 설정한다고 한다.
alias: [
  { find: '@/types', replacement: '/src/types' },
  { find: '@type', replacement: '/src/types' },
  { find: '~/types', replacement: '/src/types' },
  { find: '#types', replacement: '/src/types' }
]

 

4. paths 순서가  VS Code 자동완성 순서에 영향을 준다.

이 내용은 사실 공식문서에서는 찾아볼 수 없었는데 VS Code에서 반복적으로 겪은 부분이다.

tsconfig.app.json에 다른 예제들과 같이 @/* 경로를 먼저 설정하고, 그다음 @components/* 등의 경로를 설정했는데

자동완성으로는 @/components/를 연결해서 alias경로로 의도한 대로 써지지 않았다.

혹시나 해서 순서를 바꾸어보았더니 그 후로는 @components/로 잘 연결이 되었다. 

객체타입으로 들어간 paths속성에서 순서의 영향을 받는것이 의아하긴 하지만

GitHub이슈에도 먼저 선언한 alias가 자동완성에 우선 표시된다는 의견이 나온걸로 보아 선언 순서에도 신경을 써야 하는것 같다.

 

5. 제대로 설정을 했는데도 자동완성이 안될땐 재시작

-VSCode 재시작해보기

-Typescript 서버 재시작 (cmd/ctrl+Shift+P > "TypeScript: Restart TS Server")

 

 

 

Vite가 빌드과정을 최적화 하면서 다른 도구들과 차이점도 생기는것 같은데

이렇게 쉽게 쓰고 있는 도구일수록 프로세스가 어떻게 돌아가는지 이해를 해야 문제가 생겼을 때 디버깅도 쉽게 할 수 있는것 같다.

이젠 alias 설정 바로 할 수 있을듯!