Declaration Files(.d.ts) — 타입 선언 파일 작성과 ambient 모듈

선언 파일(.d.ts)은 JavaScript 코드의 타입 정보만 담은 파일입니다. 구현 없이 타입만 정의합니다.

선언 파일이란

TYPESCRIPT

// math.js — 일반 JavaScript
function add(a, b) {
  return a + b;
}
module.exports = { add };

// math.d.ts — 타입 선언
declare function add(a: number, b: number): number;
export { add };

.d.ts 파일은 JavaScript 라이브러리에 타입 정보를 제공하거나, 프로젝트의 전역 타입을 선언할 때 사용합니다.

전역 선언 (Ambient Declarations)

declare 키워드로 전역 변수, 함수, 타입을 선언합니다.

TYPESCRIPT

// globals.d.ts
// 전역 변수 선언
declare const API_URL: string;
declare const IS_PRODUCTION: boolean;

// 전역 함수 선언
declare function gtag(...args: any[]): void;

// 전역 인터페이스 확장
interface Window {
  analytics: {
    track(event: string, data?: Record<string, unknown>): void;
  };
}

TYPESCRIPT

// 사용 — import 없이 바로 접근
console.log(API_URL);  // OK
window.analytics.track('click'); // OK

Ambient 모듈 선언

타입이 없는 JavaScript 패키지에 타입을 제공할 수 있습니다.

TYPESCRIPT

// declarations.d.ts

// 특정 모듈에 타입 제공
declare module 'untyped-package' {
  export function doSomething(input: string): number;
  export const version: string;
}

// CSS 모듈
declare module '*.css' {
  const styles: Record<string, string>;
  export default styles;
}

// 이미지 파일
declare module '*.png' {
  const src: string;
  export default src;
}

declare module '*.svg' {
  const src: string;
  export default src;
}

// JSON 파일
declare module '*.json' {
  const value: unknown;
  export default value;
}

와일드카드 모듈

TYPESCRIPT

// 모든 하위 경로를 포함하는 모듈
declare module 'my-lib/*' {
  export function helper(): void;
}

// 사용
import { helper } from 'my-lib/utils'; // OK

@types와 DefinitelyTyped

타입이 없는 npm 패키지는 @types/패키지명으로 커뮤니티가 만든 타입을 설치할 수 있습니다.

BASH

# 예: lodash에 대한 타입
npm install --save-dev @types/lodash

# express에 대한 타입
npm install --save-dev @types/express @types/node

TypeScript는 자동으로 node_modules/@types에서 타입을 찾습니다.

JSON

// tsconfig.json에서 타입 검색 위치를 제한할 수 있음
{
  "compilerOptions": {
    "types": ["node", "jest"]  // 이 패키지의 타입만 포함
    // 또는 "typeRoots": ["./types", "./node_modules/@types"]
  }
}

선언 파일 작성 패턴

함수 라이브러리

TYPESCRIPT

// utils.d.ts
export declare function debounce<T extends (...args: any[]) => any>(
  fn: T,
  delay: number
): T;

export declare function throttle<T extends (...args: any[]) => any>(
  fn: T,
  limit: number
): T;

클래스 라이브러리

TYPESCRIPT

// database.d.ts
export declare class Database {
  constructor(connectionString: string);
  connect(): Promise<void>;
  query<T>(sql: string, params?: unknown[]): Promise<T[]>;
  close(): Promise<void>;
}

네임스페이스

TYPESCRIPT

// config.d.ts
declare namespace AppConfig {
  interface Database {
    host: string;
    port: number;
    name: string;
  }

  interface Server {
    port: number;
    cors: boolean;
  }
}

프로젝트에서 전역 타입 정의

TYPESCRIPT

// types/env.d.ts — 환경 변수 타입
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    DATABASE_URL: string;
    API_KEY: string;
    PORT?: string;
  }
}

// 사용
process.env.NODE_ENV; // 'development' | 'production' | 'test'
process.env.DATABASE_URL; // string

declaration 옵션으로 자동 생성

JSON

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,      // .d.ts 자동 생성
    "declarationDir": "./types", // 출력 경로
    "declarationMap": true    // .d.ts.map 생성 (소스맵)
  }
}

라이브러리를 배포할 때는 declaration: true로 자동 생성된 .d.ts를 함께 배포합니다.

정리

.d.ts 파일은 구현 없이 타입 정보만 담는 선언 파일이다
declare로 전역 변수, 함수, 모듈의 타입을 선언한다
CSS, 이미지 등 비-JS 파일의 import 타입은 ambient 모듈로 정의한다
@types/패키지명으로 커뮤니티 타입 정의를 설치할 수 있다
declaration: true로 TypeScript 코드에서 .d.ts를 자동 생성할 수 있다