Vite + TypeScript 프로젝트 Alias 설정 오류 해결하기

🚨 문제 코드 및 오류 상황

프로젝트 내에서 특정 폴더나 파일을 간편하게 참조하기 위해 alias 설정을 적용하려고 했는데, 아래와 같은 오류가 발생했다.

이는 TypeScript 가 설정된 alias 를 제대로 인식하지 못해 생기는 문제였다.

모듈 또는 해당 선언을 찾을 수 없습니다.​

 

먼저, 나는 tsconfig.json 에서 alias 를 다음과 같이 설정했다.

이렇게 설정한 후, alias 를 사용했을 때 오류 메시지가 발생했고,

처음에는 설정이 잘못되었거나 Vite 와 TypeScript 간 호환성 문제라고 생각했다.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@api/*": ["src/api/*"],
      "@common/*": ["src/common/*"],
      "@pages/*": ["src/pages/*"],
      "types/*": ["src/types/*"]
    }
  }
}

 

✅ 해결 방법

tsconfig.json 파일에 추가했던 alias 설정을 삭제하고, tsconfig.app.json 에 추가했다.

이 변경을 적용하자 오류가 사라지고, TypeScript 가 alias 를 정상적으로 인식하게 되었다.

 

++) 그렇다면 tsconfig.json 과 tsconfig.app.json 은 뭐가 다른 걸까?

• tsconfig.json: 프로젝트의 최상위 TypeScript 설정 파일로, 기본적인 컴파일 옵션이 정의되어 있다. 모든 설정의 기본이 되는 파일이지만, Vite 프로젝트에서는 별도로 작성한 tsconfig.app.json 을 우선 참조하지 때문에 직접 사용되지는 않는다.
• tsconfig.app.json: 프론트엔드 애플리케이션의 컴파일 설정을 정의하는 파일이다. 주로 애플리케이션에 필요한 alias, import 경로 등을 여기에서 설정한다. Vite 는 이 파일을 기본적으로 참조하므로, alias 는 이 파일에 작성해야 인식된다.
• tsconfig.node.json: 서버 측 설정 파일이다. Node.js 환경에서 사용하는 설정으로, 백엔드나 서버에서 사용할 모듈 경로 등을 정의한다.

 

++) tsconfig.app.json 에 설정해야 작동하는 이유?

Vite 는 컴파일 시 tsconfig.app.json 을 우선적으로 참조한다. 따라서 tsconfig.json 에 설정했을 때는 alias 가 제대로 인식되지 않고, tsconfig.app.json 에 설정해야 정상적으로 인식된다.

 

---

📌 alias 설정

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": resolve(__dirname, "./src"),
      "@api": resolve(__dirname, "./src/api"),
      "@common": resolve(__dirname, "./src/common"),
      "@pages": resolve(__dirname, "./src/pages"),
      "@types": resolve(__dirname, "./src/types"),
    },
  },
});

// tsconfig.app.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@api/*": ["src/api/*"],
      "@common/*": ["src/common/*"],
      "@pages/*": ["src/pages/*"],
      "types/*": ["src/types/*"]
    }
  }
}

 

---

📖 정리

1. 오류 원인: tsconfig.jso 에 alias 를 설정했으나, tsconfig.app.json 파일을 우선 참조하므로 TypeScript 에서 alias 를 인식하지 못함.
2. 해결 방법: tsconfig.json 에서 alias 설정 삭제, tsconfig.app.json 에 alias 다시 설정
3. tsconfig.json vs tsconfig.app.json vs tsconfig.node.json
   • tsconfig.json: 기본 프로젝트 설정 파일 (특수한 경우 외 직접 사용 X)
   • tsconfig.app.json: 프론트엔드 애플리메이션 설정
   • tsconfig.node.json: 서버 측 설정 파일
4. Vite 는 tsconfig.app.json 을 기본으로 참조하기 때문에 해당 파일에 설정해야 함.

 

---

💡 참고 자료

https://bluemiv.github.io/posts/vite-react-alias-path/

Vite React 앱에 Alias path 설정