타입스크립트 declare 사용법

 

declare 키워드 기능

1. 환경 선언(ambient declarations) 만들 때 사용
2. 네임스페이스 확장으로 특정 모듈이나 변수, 함수, 클래스 등이 존재한다는 것을 TypeScript 컴파일러에게 알릴 때 사용
3. d.ts를 통한 분리 관리

 

1. 환경 선언(Ambient Declarations)

declare를 사용하는 환경 선언은 TypeScript에게 특정 변수나 모듈이 존재한다고 알리기 위해 사용된다.

주로 외부 자바스크립트 라이브러리나 환경에 존재하는 변수들에 대한 타입 정보를 제공할 때 사용한다.

예시

전역 변수 선언

전역 변수 MY_GLOBAL이 자바스크립트 환경에서 이미 존재한다고 가정할 때, 다음과 같이 TypeScript에게 이 변수의 존재와 타입을 알릴 수 있다.

TypeScript 코드 내에서 MY_GLOBAL 변수를 string 타입으로 사용할 수 있다.

declare var MY_GLOBAL: string;

모듈 선언

특정 자바스크립트 라이브러리 또는 모듈이 있지만, 해당 라이브러리에 대한 타입 선언이 없을 때, 다음과 같이 모듈을 선언할 수 있다.

example-module을 import하여 exampleFunction을 TypeScript에서 타입 체크와 함께 안전하게 사용할 수 있다.

// Node.js의 일부 모듈에 대한 선언
declare module 'example-module' {
  export function exampleFunction(): void;
}

2. 네임스페이스 확장

기존의 타입이나 인터페이스, 클래스 등에 새로운 속성을 추가할 때 **declare**를 사용하여 확장할 수 있다.

예시

인터페이스 확장

기존의 Window 인터페이스에 새로운 속성을 추가하고자 할 때, 다음과 같이 확장할 수 있다.

window.customProperty를 string 타입으로 안전하게 사용할 수 있습니다.

declare global {
  interface Window {
    customProperty: string;
  }
}

3. 타입 선언 파일 생성 (.d.ts)

환경 선언과, 네임스페이스 확장 방법으로 라이브러리나 프로젝트 전반에 걸쳐 사용할 타입 정의를 별도의 선언 파일(.d.ts)에 분리하여 관리할 수 있다.

이 파일 내에서는 declare 키워드를 사용하여 전역 변수, 모듈, 네임스페이스 등의 타입을 선언할 수 있으며, 이러한 선언들은 TypeScript에 의해 자동으로 인식되어 사용된다.

예시

전역 변수 선언

웹 사이트에서 사용되는 외부 자바스크립트 라이브러리가 전역 변수 SomeGlobalLibrary를 제공한다고 가정한다.

이 라이브러리의 API를 TypeScript에서 사용하려면, 해당 API의 타입 정보를 제공하는 .d.ts 파일을 생성해야 한다.

// some-global-library.d.ts
declare var SomeGlobalLibrary: {
  initialize(config: { apiKey: string; useSandbox: boolean }): void;
  doSomething(value: string): number;
};

모듈 선언

특정 npm 패키지에 대한 타입 선언 파일이 없는 경우, 직접 모듈의 타입 선언을 제공할 수 있다.

예를 들어, **some-npm-module**이라는 패키지가 있고, 이 모듈이 기본적으로 함수를 하나 내보낸다고 가정한다.

이 타입 선언 파일을 사용하면, **some-npm-module**의 doSomething 함수를 TypeScript에서 타입 오류 없이 사용할 수 있다.

// some-npm-module.d.ts
declare module "some-npm-module" {
  export default function doSomething(): void;
}

네임스페이스 확장

기존의 JavaScript 라이브러리나 환경이 특정 객체에 대한 추가적인 메서드나 속성을 제공하는 경우, 객체의 타입을 확장하여 추가적인 멤버에 대한 타입 정보를 제공할 수 있다.

예를 들어, jQuery의 $ 객체에 새로운 메서드를 추가했다고 가정한다.

이 선언 파일을 추가하면, jQuery 객체($)에 대한 타입 정의에 newMethod 메서드가 포함되어, 해당 메서드를 TypeScript에서 오류 없이 사용할 수 있습니다.

// jquery-plugin.d.ts
interface JQuery {
  newMethod(): void;
}

활용

window 객체에 새로운 속성 추가

TypeScript에서 window 객체에 새로운 속성을 추가하려면, 먼저 Window 인터페이스를 확장해야 한다. 이를 통해 TypeScript에게 새 속성에 대해 알려주고, 해당 속성에 대한 타입 정보를 제공할 수 있다.

이 방법은 window 객체에 직접적으로 속성이나 메서드를 추가해야 할 때 유용하며, 이렇게 추가된 속성이나 메서드는 window 객체의 일부로 사용된다.

예를 들어, window 객체에 'PasongTest'라는 속성을 추가하고자 한다면, 다음과 같은 단계를 따른다.

1. 전역 선언 파일(예: globals.d.ts)을 생성하거나 수정합니다.
2. 이 파일 내에서 Window 인터페이스를 확장하여 PasongTest 속성을 추가하고, 이 속성의 타입을 정의합니다.

// globals.d.ts
interface Window {
  PasongTest: any;
}

이제 window.PasongTest 속성을 전역적으로 타입 안전하게 사용할 수 있게 됩니다.

이 방식으로 추가된 속성은 TypeScript 프로젝트 내의 모든 파일에서 인식되며, 해당 속성의 타입 체크가 가능해집니다.

my-app/
├── src/
│   ├── globals.d.ts
│   ├── App.tsx
│   ├── index.tsx
│   └── ...

전역 객체(declare global)에 속성 타입 추가

window 객체도 아니고 전역 네임스페이스에 추가할 때는 declare global 블록을 통해 전역 스코프에 직접 선언을 추가하면 된다.

interface PasongTest {
	config: {
		escapeHTML(value: string): string;
	};
}
declare global {
	const PasongTest : PasongTest ;
}
export {};

declare global 블록를 통해서 전역 상수 스코프에 직접 PasongTest 에 대한 타입을 선언한다.

이는 전역 네임스페이스에 직접 추가되며, PasongTest 는 어디서나 바로 사용할 수 있다.

이는 프로젝트의 어떤 파일에서도 직접 접근하여 사용할 수 있게 된다.

declare 키워드 기능

1. 환경 선언(ambient declarations) 만들 때 사용
2. 네임스페이스 확장으로 특정 모듈이나 변수, 함수, 클래스 등이 존재한다는 것을 TypeScript 컴파일러에게 알릴 때 사용
3. d.ts를 통한 분리 관리

1. 환경 선언(Ambient Declarations)

declare를 사용하는 환경 선언은 TypeScript에게 특정 변수나 모듈이 존재한다고 알리기 위해 사용된다.

주로 외부 자바스크립트 라이브러리나 환경에 존재하는 변수들에 대한 타입 정보를 제공할 때 사용한다.

예시

전역 변수 선언

전역 변수 MY_GLOBAL이 자바스크립트 환경에서 이미 존재한다고 가정할 때, 다음과 같이 TypeScript에게 이 변수의 존재와 타입을 알릴 수 있다.

TypeScript 코드 내에서 MY_GLOBAL 변수를 string 타입으로 사용할 수 있다.

declare var MY_GLOBAL: string;

모듈 선언

특정 자바스크립트 라이브러리 또는 모듈이 있지만, 해당 라이브러리에 대한 타입 선언이 없을 때, 다음과 같이 모듈을 선언할 수 있다.

example-module을 import하여 exampleFunction을 TypeScript에서 타입 체크와 함께 안전하게 사용할 수 있다.

// Node.js의 일부 모듈에 대한 선언
declare module 'example-module' {
  export function exampleFunction(): void;
}

2. 네임스페이스 확장

기존의 타입이나 인터페이스, 클래스 등에 새로운 속성을 추가할 때 **declare**를 사용하여 확장할 수 있다.

예시

인터페이스 확장

기존의 Window 인터페이스에 새로운 속성을 추가하고자 할 때, 다음과 같이 확장할 수 있다.

window.customProperty를 string 타입으로 안전하게 사용할 수 있습니다.

declare global {
  interface Window {
    customProperty: string;
  }
}

3. 타입 선언 파일 생성 (.d.ts)

환경 선언과, 네임스페이스 확장 방법으로 라이브러리나 프로젝트 전반에 걸쳐 사용할 타입 정의를 별도의 선언 파일(.d.ts)에 분리하여 관리할 수 있다.

이 파일 내에서는 declare 키워드를 사용하여 전역 변수, 모듈, 네임스페이스 등의 타입을 선언할 수 있으며, 이러한 선언들은 TypeScript에 의해 자동으로 인식되어 사용된다.

예시

전역 변수 선언

웹 사이트에서 사용되는 외부 자바스크립트 라이브러리가 전역 변수 **SomeGlobalLibrary**를 제공한다고 가정한다.

이 라이브러리의 API를 TypeScript에서 사용하려면, 해당 API의 타입 정보를 제공하는 .d.ts 파일을 생성해야 한다.

// some-global-library.d.ts
declare var SomeGlobalLibrary: {
  initialize(config: { apiKey: string; useSandbox: boolean }): void;
  doSomething(value: string): number;
};

모듈 선언

특정 npm 패키지에 대한 타입 선언 파일이 없는 경우, 직접 모듈의 타입 선언을 제공할 수 있다.

예를 들어, some-npm-module이라는 패키지가 있고, 이 모듈이 기본적으로 함수를 하나 내보낸다고 가정한다.

이 타입 선언 파일을 사용하면, some-npm-module* doSomething 함수를 TypeScript에서 타입 오류 없이 사용할 수 있다.

// some-npm-module.d.ts
declare module "some-npm-module" {
  export default function doSomething(): void;
}

네임스페이스 확장

기존의 JavaScript 라이브러리나 환경이 특정 객체에 대한 추가적인 메서드나 속성을 제공하는 경우, 객체의 타입을 확장하여 추가적인 멤버에 대한 타입 정보를 제공할 수 있다.

 

예를 들어, jQuery의 $ 객체에 새로운 메서드를 추가했다고 가정한다.

 

이 선언 파일을 추가하면, jQuery 객체($)에 대한 타입 정의에 newMethod 메서드가 포함되어, 해당 메서드를 TypeScript에서 오류 없이 사용할 수 있습니다.

// jquery-plugin.d.ts
interface JQuery {
  newMethod(): void;
}

활용

window 객체에 새로운 속성 추가

TypeScript에서 window 객체에 새로운 속성을 추가하려면, 먼저 Window 인터페이스를 확장해야 한다. 이를 통해 TypeScript에게 새 속성에 대해 알려주고, 해당 속성에 대한 타입 정보를 제공할 수 있다.

 

이 방법은 window 객체에 직접적으로 속성이나 메서드를 추가해야 할 때 유용하며, 이렇게 추가된 속성이나 메서드는 window 객체의 일부로 사용된다.

 

예를 들어, window 객체에 'PasongTest'라는 속성을 추가하고자 한다면, 다음과 같은 단계를 따른다.

1. 전역 선언 파일(예: globals.d.ts)을 생성하거나 수정합니다.
2. 이 파일 내에서 Window 인터페이스를 확장하여 PasongTest 속성을 추가하고, 이 속성의 타입을 정의합니다.

// globals.d.ts
interface Window {
  PasongTest: any;
}

 

이제 window.PasongTest 속성을 전역적으로 타입 안전하게 사용할 수 있게 됩니다.

이 방식으로 추가된 속성은 TypeScript 프로젝트 내의 모든 파일에서 인식되며, 해당 속성의 타입 체크가 가능해집니다.

 

my-app/
├── src/
│   ├── globals.d.ts
│   ├── App.tsx
│   ├── index.tsx
│   └── ...

전역 객체(declare global)에 속성 타입 추가

window 객체도 아니고 전역 네임스페이스에 추가할 때는 declare global 블록을 통해 전역 스코프에 직접 선언을 추가하면 된다.

interface PasongTest {
	config: {
		escapeHTML(value: string): string;
	};
}
declare global {
	const PasongTest : PasongTest ;
}
export {};

 

declare global 블록를 통해서 전역 상수 스코프에 직접 PasongTest 에 대한 타입을 선언한다.

 

이는 전역 네임스페이스에 직접 추가되며, PasongTest 는 어디서나 바로 사용할 수 있다.

이는 프로젝트의 어떤 파일에서도 직접 접근하여 사용할 수 있게 된다.