Vite에서 Path Alias 설정하기
React에서 프로젝트를 진행하다 보면 상대경로 지옥에 빠지는 경우가 많다.
import Button from "../../../components/button/Button";이와 같은 경로는 보기 불편하고 유지보수하기도 어렵다.
이럴때 유용한 게 바로 Path Alias 이다.
import Button from "@components/button/Button";Path Alias를 적용하면 위와 같이 깔끔하게 바꿀 수 있다.
📕 Path Alias 설정하기
Alias를 설정하기 위해서는 vite.config.ts와
TypeScript를 사용 중이라면 tsconfig.json 또는 tsconfig.app.json을 수정해주면 사용할 수 있다.
📖 Vite.config.ts 설정
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from 'path';
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
"@components": path.resolve(__dirname, "src/components"),
"@pages": path.resolve(__dirname, "src/pages"),
"@hooks": path.resolve(__dirname, "src/hooks"),
"@api": path.resolve(__dirname, "src/api"),
"@styles": path.resolve(__dirname, "src/styles"),
"@assets": path.resolve(__dirname, "src/assets"),
"@utils": path.resolve(__dirname, "src/utils"),
},
},
});
이렇게 설정하면 기존 ../../components/button 처럼 복잡했던 경로를 @components/button으로 간단하게 사용할 수 있다.
하지만!
TypeScript를 사용 중이라면 Vite에서는 잘 작동하지만, VS Code에서 에러가 발생할 수 있다.
~~모듈 또는 해당 형식 선언을 찾을 수 없습니다.ts(2307)
이 경우 tsconfig.json에도 별도로 설정을 추가해줘야 한다.
💡 path 에서 오류가 발생할때
path.resolve()는 Node.js에 내장된 API다.
JS에서는 그냥 사용해도 되지만, TypeScript에서는 Node 타입 정의가 없으면 오류가 발생할 수 있다.
vite.config.js→ 그냥 사용 가능
vite.config.ts→path,process등을 쓰려면 @types/node 필요
npm install -D @types/node이렇게 설치해주면 에러가 사라진다.
📖 tsconfig.json 설정
"compilerOptions": {
"baseUrl": "./src",
"paths": {
"@components/*": ["components/*"],
"@pages/*": ["pages/*"],
"@hooks/*": ["hooks/*"],
"@api/*": ["api/*"],
"@styles/*": ["styles/*"],
"@assets/*": ["assets/*"],
"@utils/*": ["utils/*"]
}
}이렇게 설정하면 VS Code에서도 Path Alias 관련 오류가 사라질 것이다.
💡 에러가 사라지지 않을때
이 문제로 정말 오래 고생했다.
VS Code를 수십 번 껐다 켜고, TypeScript 서버를 재시작하고, node_modules와 캐시를 지우는 등
인터넷에 있는 거의 모든 방법을 시도했지만 해결되지 않았다.
그렇게 수십 번의 삽질 끝에, 마침내 원인을 찾았다.
🧩 문제의 원인
내 프로젝트의 tsconfig.json 파일은 아래와 같은 구조였다.
{
"files": [],
"references": [
{ "path": "./tsconfig.app.json" },
{ "path": "./tsconfig.node.json" }
]
}이런 구조는 TypeScript에서 Project References라고 불리는 방식이다.
즉, 루트 설정은 실제 컴파일에 사용되지 않고,
하위 설정 파일(tsconfig.app.json,tsconfig.node.json)만을 참조한다.
처음엔 대부분의 글을 참고해 루트 tsconfig.json에 compilerOptions를 추가했지만 아무 효과가 없었다
그 이유는 루트 설정이 직접 사용되지 않기 때문이다.
baseUrl, paths 같은 설정은 하위 설정 파일에 직접 작성해야 한다.
📘 구조에 대한 이해가 필요하다
예전에는 모든 TypeScript 설정을 tsconfig.json 하나에 넣었지만,
최근에는 프로젝트 구조가 분리되는 경우가 많다:
tsconfig.app.json→ 프론트엔드 앱 코드용
tsconfig.node.json→ 빌드/테스트용 Node 코드
따라서 실제 앱 코드에서 Path Alias를 사용하고 싶다면,
tsconfig.app.json 에 아래와 같이 설정을 넣어줘야 한다.
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@components/*": ["components/*"],
"@pages/*": ["pages/*"],
...
}
}
}이렇게 수정하니 드디어 에러도 사라지고, import 경로도 깔끔하게 작동했다.
✅ 정리
- 루트 tsconfig.json은 단순히 다른 설정 파일들을 참조할 뿐이다.
- 실제로 컴파일에 사용되는 설정(compilerOptions, paths, baseUrl)은 하위 설정 파일에 직접 넣어야 한다.
- 구조를 이해하지 못한 채 루트에만 설정하면, 아무리 수정해도 적용되지 않는다.
📖 vite-tsconfig-paths
매번 alias를 등록할 때마다 vite.config와 tsconfig두 파일을 수정하는 건 꽤 번거롭다.
이럴 땐 vite-tsconfig-paths 플러그인을 사용하면 더 간편하게 설정할 수 있다.
npm install vite-tsconfig-paths -D그리고 vite.config.ts에 아래와 같이 추가해주면 된다.
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [
react(),
tsconfigPaths(),
],
});
이렇게 하면 tsconfig.json에서 설정한 Path Alias를 자동으로 읽어오므로
별도로 vite.config.ts에서 매번 alias를 설정할 필요가 없다.
🏁 마무리
Path Alias는 작은 설정이지만,
프로젝트의 가독성과 유지보수성에 큰 영향을 준다.
처음엔 살짝 헷갈릴 수 있지만 구조만 이해하면 어렵지 않으니
앞으로는 더 깔끔한 경로로 코드를 작성해보자! 😎
참조
TypeScript: TSConfig Reference
React + TS 환경에서 path alias 설정하기
Vite기반 React 프로젝트에서 Path Aliasing 설정하기
