개요

TypeScript의 declare 키워드는 외부에서 이미 구현된 값의 타입 정보를 컴파일러에 알려주는 용도임 실제 구현은 다른 런타임 환경이나 스크립트에 존재하고, TypeScript는 타입 검사만 수행함 선언은 자바스크립트 코드로 출력되지 않음

핵심 개념

  • declare function: 외부에 존재하는 함수의 시그니처만 제공하는 선언
  • 사용 위치: 주로 .d.ts 선언 파일, 필요 시 .ts에서도 가능하지만 빌드 결과물에는 코드가 생성되지 않음
  • 목적: 컴파일 타임에 타입을 인지시켜 오류를 줄이고, IDE 보조 기능을 활성화함

언제 사용하나

  • 타입 정보가 없는 외부 자바스크립트 라이브러리 사용 시
  • 글로벌로 노출된 함수나 변수를 TypeScript가 모를 때
  • JS와 TS 혼용 프로젝트에서 점진적 마이그레이션을 진행할 때

예시

  1. 글로벌 함수 선언
// 이미 어딘가에서 구현된 전역 함수가 있다고 가정
// my-globals.d.ts
declare function myGlobalFunction(msg: string): void

이렇게 선언하면 TypeScript가 함수 존재와 시그니처를 인식함

  1. 모듈 타입 선언
// ambient 모듈 선언
declare module "some-external-lib" {
  export function externalFunc(): void
}

해당 모듈 임포트 시 타입 정보를 활용 가능

  1. 함수 오버로드 선언이 필요한 경우
declare function search(q: string): string[]
declare function search(q: RegExp): string[]

런타임 구현은 외부에 있고, 타입 시스템에 가능한 호출 형태만 명시

주의 사항과 한계

  • declare는 타입 정보만 제공, 본문을 가진 구현과 함께 사용할 수 없음
  • 선언만 있고 런타임 구현이 없으면 ReferenceError 등 런타임 오류 발생 가능
  • 글로벌 선언은 범위를 오염시킬 수 있음. 모듈 선언 형태 선호, 불가피할 때에만 declare global 사용 권장
  • any 남발 지양. 최소한의 정확한 시그니처 제공이 유지보수에 유리함
  • 타입 패키지가 존재하면 직접 선언보다 공식 타입 정의(@types 등) 우선 사용 권장

베스트 프랙티스

  • 선언은 가능한 별도 .d.ts 파일로 분리
  • 전역 보강이 필요하면 명시적으로 영역을 한정
declare global {
  function myGlobalFunction(msg: string): void
}
export {}
  • 실제 런타임 유무를 항상 검증. 빌드 단계에서는 통과하더라도 실행 환경에 구현이 없으면 실패함

마무리

declare function은 구현 없이 타입 시스템에 외부 함수의 시그니처를 알려주는 수단임 타입 안전성과 도구 지원을 얻되, 선언과 실제 구현이 일치하도록 관리하는 것이 핵심임 주 사용처는 .d.ts 파일이며, 외부 라이브러리 통합과 점진적 TS 도입에 유용함

참고자료