[TECH-QA] 타입 정의 파일(.d.ts)

Posted 4 months Updated 4 months

By 베짱이가 되고싶은 개미。

interface나 type으로 정의하여 쓸수 있는데 d.ts로 사용하는 이유 대하여

타입스크립트에서 interface나 type을 사용해 타입을 정의할 수 있는데도 .d.ts 파일을 사용하는 이유는 사용 목적과 맥락의 차이에 있습니다. .d.ts 파일은 주로 선언 파일(Declaration File)로서 특정한 역할을 수행하며, 일반적인 interface나 type 정의와는 다른 상황에서 유용합니다. 아래에서 .d.ts를 사용하는 이유와 그 장점을 구체적으로 설명하겠습니다.

자바스크립트와의 통합: 기존 자바스크립트 코드나 외부 라이브러리에 타입을 추가할 때.
선언과 구현 분리: 타입 정의를 별도로 관리하고 런타임 코드에 영향을 주지 않으려 할 때.
글로벌 타입 제공: 프로젝트 전체에서 사용할 공통 타입을 전역적으로 선언할 때.
라이브러리 배포: 타입스크립트 사용자를 위해 타입 정의를 제공할 때.

반면, 프로젝트 내부에서만 타입을 정의하고 사용할 때는 interface나 type을 .ts 파일에 작성하는 것이 더 간단하고 적합합니다. .d.ts는 특히 외부와의 인터페이스를 다룰 때 빛을 발하는 도구라고 볼 수 있습니다.

간단한 자바스크립트 함수에 타입 정의 추가

기존 자바스크립트 파일에 타입이 없는 상황을 가정하고, .d.ts 파일로 타입을 제공하는 예제입니다.

📝 자바스크립트 파일 (math.js)

function add(a, b) {
  return a + b;
}

module.exports = { add };

📝 타입 선언 파일 (math.d.ts)

export function add(a: number, b: number): number;

📝 타입스크립트에서 사용 (app.ts)

import { add } from "./math";

const result = add(5, 3); // result는 number 타입으로 추론됨
console.log(result); // 8

// add("5", "3"); // 오류: 'string' 타입은 'number' 타입에 할당할 수 없음

math.js는 타입 정보가 없는 자바스크립트 파일이지만, math.d.ts에서 add 함수의 매개변수와 반환 타입을 정의해줍니다. 타입스크립트는 이 선언 파일을 참조하여 타입 검사를 수행하며, 잘못된 타입 사용 시 오류를 발생시킵니다. 타입정의는 컴파일 시 타입 체크에 사용되고 자바스크립트로 변환된 런타임 코드에는 타입이 직접 포함되지 않습니다. 실제 실행되는 로직만 남습니다.

Lodash와 같은 외부 라이브러리 통합

Lodash는 인기 있는 자바스크립트 유틸리티 라이브러리입니다. 타입스크립트에서 이를 사용하려면 @types/lodash와 같은 타입 정의 패키지를 설치하거나 직접 .d.ts 파일을 작성할 수 있습니다.

📝 Lodash 설치

npm install lodash
npm install --save-dev @types/lodash //타입 정의 설치 (DefinitelyTyped 제공)

📝 타입스크립트에서 사용

import _ from "lodash";

const numbers = [1, 2, 3, 4];
const sum = _.sum(numbers); // sum은 number 타입으로 추론됨
console.log(sum); // 10

// _.sum("not an array"); // 오류: 'string'은 'ArrayLike<number>' 타입에 할당할 수 없음

@types/lodash 패키지는 Lodash의 모든 함수에 대한 타입 정의를 제공합니다. 예를 들어, _.sum은 숫자 배열을 받아 숫자를 반환하는 함수로 타입이 정의되어 있으며, 타입스크립트는 이를 기반으로 타입 검사를 수행합니다.

React 컴포넌트와 통합

React는 자바스크립트로 작성된 라이브러리지만, 타입스크립트에서 사용하려면 타입 정의가 필요합니다.
@types/react와 @types/react-dom을 통해 이를 해결할 수 있습니다.

📝 React 설치

npm install react react-dom
npm install --save-dev @types/react @types/react-dom

📝 타입스크립트로 React 컴포넌트 작성

import React from "react";
import ReactDOM from "react-dom";

interface Props {
  name: string;
}

const Greeting: React.FC<Props> = ({ name }) => {
  return <h1>Hello, {name}!</h1>;
};

ReactDOM.render(<Greeting name="Alice" />, document.getElementById("root"));

// <Greeting name={123} /> // 오류: 'number' 타입은 'string' 타입에 할당할 수 없음

@types/react는 React의 타입 정의를 제공하며, React.FC와 같은 타입을 통해 함수형 컴포넌트의 props 타입을 정의할 수 있습니다. name props가 string으로 정의되었으므로, 숫자를 전달하면 컴파일 오류가 발생합니다.

React에 커스텀 타입을 추가하고 싶다면 커스텀 .d.ts로 확장 (선택적)

만약 React에 커스텀 타입을 추가하고 싶다면, 다음과 같이 custom.d.ts 파일을 작성할 수 있습니다. 이 경우 customProp을 React 컴포넌트에서 타입 안전하게 사용할 수 있습니다.

📝 custom.d.ts

declare module "react" {
  interface CustomComponentProps {
    customProp: boolean;
  }
}

📝 CustomComponent.tsx

import React from "react";

const CustomComponent: React.FC<CustomComponentProps> = ({ customProp }) => {
  return <div>{customProp ? "Yes" : "No"}</div>;
};

export default CustomComponent;

📝 App.tsx

import React from "react";
import CustomComponent from "./CustomComponent";

const App: React.FC = () => {
  return (
      <CustomComponent customProp={true} />
  );
};

export default App;

커스텀 .d.ts로 확장

타입스크립트가 인식하지 못하는 타입이나 타입스크립트 내에서 사용할 타입들을 정의 할때 예로 svg 파일을 타입스크립트에서 불러올 수 있게 하도록 custom.d.ts 파일을 생성해준다.

📝 custom.d.ts

declare module "*.svg" {
  import * as React from "react";

  interface CustomSVGProps {
    title?: string;
  }

  // SVG 컴포넌트의 전체 props 타입 정의
  type SVGComponentProps = React.SVGProps<SVGSVGElement> & CustomSVGProps;

  // ReactComponent를 함수형 컴포넌트로 선언
  export const ReactComponent: React.FunctionComponent<SVGComponentProps>;

  // SVG 파일의 기본 내보내기로 문자열 URL 정의
  const path: string;
  export default path;
}

이 선언을 사용하면 SVG 파일을 다음과 같이 가져와 활용할 수 있습니다

import { ReactComponent as Icon } from "./icon.svg";
import iconPath from "./icon.svg";

const App: React.FC = () => (
  <div>
    <Icon width="50" height="50" fill="blue" title="My Icon" />
    <img src={iconPath} alt="Icon" width="50" height="50" />
  </div>
);

Icon은 SVGComponentProps 타입을 기반으로 타입 검사가 이루어지며, title은 옵셔널로 사용 가능합니다.
iconPath는 string 타입으로 이미지 소스로 활용됩니다.

구현 코드와 타입 정의의 분리

타입 정의와 실제 구현 코드를 분리하고 싶을 때, .d.ts 파일은 선언만 포함하고 이는 런타임에 영향을 주지 않습니다. 반면 .ts 파일에 interface나 type과 함께 구현 코드를 섞으면 컴파일 시 자바스크립트 코드로 변환되어 런타임에 포함됩니다.

📝 .ts 파일에 모두 작성(math.ts)

interface MathOperation {
  (a: number, b: number): number;
}
const add: MathOperation = (a, b) => a + b;
export { add };

math.ts 컴파일 결과: interface는 사라지고 구현 코드만 남음.

📝 math.d.ts

export interface MathOperation {
  (a: number, b: number): number;
}
export const add: MathOperation;

📝 math.js

const add = (a, b) => a + b;
module.exports = { add };
export const add: MathOperation;

선언과 구현을 분리하면 실제 실행되는 로직(구현)은 별도의 소스 파일에 두고 타입 정의는 주로 컴파일 타임에 사용되어 코드의 정합성을 확인하거나 개발자에게 힌트를 주는 역할을 하지만, 런타임에 실행되는 기계어 코드나 프로그램의 동작에는 직접적인 영향을 미치지 않습니다. 타입 정의만 공유하거나 재사용하기 쉬워집니다. 특히 외부 라이브러리와 통합할 때 유용합니다.

interface/type과 .d.ts의 차이점 요약

특징	사용범위	구현 포함 여부	모듈 통합	전역 선언	목적
interface / type	타입스크립트 코드 내부에서만 유효	.ts 파일 내에서 구현과 함께 사용 가능	외부 모듈의 타입 수정 불가	import/export 필요	프로젝트 내 타입 정의
.d.ts 파일	자바스크립트와 타입스크립트 연결 가능	선언만 포함, 구현은 별도 파일에서	declare module로 외부 모듈 타입 정의 가능	전역 타입 정의 가능 (declare 사용)	외부 코드와의 인터페이스 역할