d.ts

d.ts 파일

d.ts 파일은 타입 정의만 구현된 TypeScript 선언 파일을 말합니다.

---

• 타입 정의 제공

  JavaScript로 작성된 라이브러리를 TypeScript에서 사용할 때 타입 정보를 제공.

• 코드 실행 없이 타입 검사 가능

  .d.ts 파일은 실행되지 않고, 오직 TypeScript의 타입 검사에만 사용됨.

• 전역 타입 선언 가능

  프로젝트 전체에서 사용할 전역 변수나 타입을 정의하는 용도로 사용.

---

필요한 이유

Javascript로만 작성된 모듈이나 패키지를 타입스크립트 프로젝트에서 설치해서 사용할 때, Type을 알 수 없다는 문제가 발생합니다.

기본적으로는 any 타입

이 때, 타입 정의만을 담은 .d.ts 파일을 만들어서 제공하면 타입과 함께 활용할 수 있습니다.

---

declare

declare 키워드는 TypeScript에서 타입 정보를 정의할 때 사용합니다.

주로 전역 변수, 함수, 네임스페이스, 모듈, 클래스 등의 타입을 정의할 때 사용됩니다.

---

전역 타입 정의

// global.d.ts
declare const APP_NAME: string;

declare function logMessage(message: string): void;

declare namespace MyNamespace {
  interface User {
    id: number;
    name: string;
  }
}

---

console.log(APP_NAME); // 정상적으로 사용 가능

logMessage("Hello TypeScript!");

const user: MyNamespace.User = { id: 1, name: "Alice" };

---

모듈 타입 정의

declare module 'module-name' {}

// myModule.d.ts
declare module "my-library" {
  export function greet(name: string): string;

  export const version: string;
}

---

import { greet, version } from "my-library";

console.log(greet("Alice"));
console.log(version);

---

Javascript 라이브러리의 타입 정의

기존 Javascript 파일에 타입을 정의해 사용할 수 있습니다.

// utils.js
export function add(a, b) {
  return a + b;
}

export const PI = 3.14;

---

//utils.d.ts
declare module "./utils" {
  export function add(a: number, b: number): number;

  export const PI: number;
}

---

import { add, PI } from "./utils";

console.log(add(2, 3)); // 5
console.log(PI); // 3.14

---

특정 모듈 타입 확장

이 방식은 해당 모듈을 import한 파일에서만 타입이 확장되므로, 특정 파일 내에서만 유효하게 타입을 수정할 수 있습니다.

특정 모듈에 대해 로컬로만 확장하고 싶을 때 유용합니다.

// types/express.d.ts
declare module "express" {
  interface Request {
    user?: User;
  }
}

express 모듈을 임포트한 파일 내에서만 유효합니다.

---

전역 확장

만약 전체 프로젝트에서 타입을 확장하고 싶다면, declare global을 사용합니다.

// types/express.d.ts
import "express";

declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

프로젝트 내의 모든 파일에서 Request 타입을 확장된 형태로 사용할 수 있습니다.