VSCode, Cursor - TypeScript 경로 별칭(@) 자동 import가 안 될 때

VS Code/Cursor에서 @/components 같은 경로 별칭을 설정한 상황에서
cmd + . 단축키로 import를 추가할 때 ./components처럼 상대 경로로 가져와지는 문제를 겪었다.

문제 상황

리액트 프로젝트에서 TypeScript 경로 별칭(path alias)을 설정한 상황:

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

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

위와 같이 설정하였고, 코드에서도 @/components/ui/button 같은 경로를 사용이 잘 되는 것을 확인했음에도
자동 완성으로 import를 추가하면 계속 상대 경로(./components/ui/button)로 가져와져서 번거롭게 수동으로 @/로 바꿔야 하는 상황이었다.

해결 방법

이 현상은 TypeScript 언어 서버의 기본 동작 방식 때문이라고 한다.
VS Code/Cursor의 TypeScript 설정을 통해 import 시 경로 별칭을 우선 사용하도록 변경하여 해결하였다.

settings.json 파일에 다음과 같이:

{
  "typescript.preferences.importModuleSpecifier": "non-relative", // TypeScript에서 상대 경로 대신 절대 경로 사용 선호
  "javascript.preferences.importModuleSpecifier": "non-relative" // JavaScript에서 상대 경로 대신 절대 경로 사용 선호"
  
  "typescript.tsdk": "node_modules/typescript/lib", // TypeScript 언어 서버가 사용할 TypeScript 라이브러리 경로 지정
  // 내장 TypeScript가 아닌 프로젝트 폴더의 node_modules/typescript/lib 안에 있는 타입스크립트 엔진 사용

}

importModuleSpecifier 설명

importModuleSpecifier 설정에는 다음 옵션이 있다고 한다:

{
  "typescript.preferences.importModuleSpecifier": "relative"  // 상대 경로 선호 (기본값)
  // 또는
  "typescript.preferences.importModuleSpecifier": "non-relative"  // 경로 별칭 선호
  // 또는
  "typescript.preferences.importModuleSpecifier": "project-relative"  // 프로젝트 루트 기준
}