TypeScript 에서 alias를 사용할 때 주의할 점 : Cannot import type declaration files

📍 문제 상황

• tsconfig.json에서 아래와 같이 alias를 설정

"paths": {
  "@types/*": ["src/types/*"],  // ❗ 여기에 주의
  "@components/*": ["src/components/*"],
  "@utils/*": ["src/utils/*"]
}

• 이후 src/types/SelectOption.ts에 타입을 정의하고 아래처럼 import하니 다음과같은 오류 발생

import type { SelectOption } from "@types/SelectOption";

❌ Cannot import type declaration files. Consider importing 'SelectOption' instead of '@types/SelectOption'.

---

📍 원인

• @types/*는 TypeScript가 특별하게 취급하는 예약된 네이밍 규칙이다.
• @types라는 prefix는 TypeScript에서 DefinitelyTyped의 타입 패키지 (@types/react 등..)로 특별하게 인식되기 때문에 사용하면 안됨.

(ex. 변수명으로 int, function과 같은 예약어를 사용하지 않는것과 동일한 이유)

📚 참고: DefinitelyTyped란?

DefinitelyTyped

• DefinitelyTyped는 JavaScript 라이브러리용 타입 정의들을 모아둔 GitHub 저장소로, TS용 타입 정보가 없는 JS 라이브러리에 타입을 정의해놓은 오픈소스 라이브러리 .
• 이 라이브러리를 설치하면 TypeScript가 자동으로 인식하고 추론에 활용할 수 있다.

---

📍 해결 방법

• @types/라는 alias prefix는 사용하지 말고, 아래와 같이 변경

추천 alias	설명
@custom-types	프로젝트 전용 타입 정의
@models	도메인 모델 중심의 타입 정의
@schemas	API 요청/응답 스키마 등
@ui-types	UI 컴포넌트 관련 타입

- "@types/*": ["src/types/*"]
+ "@custom-types/*": ["src/types/*"]