JavaScript 생태계 잠금 해제: TypeScript Declaration 파일 심층 분석

TypeScript는 JavaScript의 역동적인 세계에 정적 타이핑을 도입하여 현대 웹 개발에 혁명을 일으켰습니다. 이러한 타입 안전성은 컴파일 시간에 오류를 포착하고, 강력한 편집기 자동 완성을 가능하게 하며, 대규모 코드베이스를 훨씬 더 유지 관리하기 쉽게 만드는 놀라운 이점을 제공합니다. 그러나 기존 JavaScript 라이브러리의 광대한 생태계를 사용하려고 할 때 주요 과제가 발생합니다. 대부분 TypeScript로 작성되지 않았습니다. 엄격하게 타입이 지정된 TypeScript 코드는 타입이 지정되지 않은 JavaScript 라이브러리의 모양, 함수 및 변수를 어떻게 이해할까요?

정답은 TypeScript Declaration 파일에 있습니다. .d.ts 확장자로 식별할 수 있는 이러한 파일은 TypeScript와 JavaScript 세계를 잇는 필수적인 다리입니다. 실제 구현을 포함하지 않고 타사 라이브러리의 타입을 설명하는 청사진 또는 API 계약 역할을 합니다. 이 종합 가이드에서는 TypeScript 프로젝트에서 JavaScript 라이브러리에 대한 타입 정의를 자신 있게 관리하는 데 필요한 모든 것을 살펴봅니다.

TypeScript Declaration 파일이란 정확히 무엇일까요?

다른 언어만 사용하는 계약자를 고용했다고 상상해 보세요. 그들과 효과적으로 협력하려면 번역가 또는 당신과 그들 모두가 이해하는 언어로 된 자세한 지침 세트가 필요합니다. declaration 파일은 TypeScript 컴파일러(계약자)에 대해 정확히 이 목적을 수행합니다.

.d.ts 파일에는 타입 정보만 포함됩니다. 여기에는 다음이 포함됩니다.

• 함수 및 메서드에 대한 서명(매개변수 타입, 반환 타입).
• 변수 및 해당 타입에 대한 정의.
• 복잡한 객체에 대한 인터페이스 및 타입 별칭.
• 속성 및 메서드를 포함한 클래스 정의.
• 네임스페이스 및 모듈 구조.

결정적으로 이러한 파일에는 실행 가능한 코드가 없습니다. 정적 분석 전용입니다. Lodash와 같은 JavaScript 라이브러리를 TypeScript 프로젝트로 가져올 때 컴파일러는 해당 declaration 파일을 찾습니다. 찾으면 코드를 검증하고, 지능적인 자동 완성을 제공하고, 라이브러리를 올바르게 사용하고 있는지 확인할 수 있습니다. 그렇지 않으면 다음과 같은 오류가 발생합니다. Could not find a declaration file for module 'lodash'.

Declaration 파일이 전문 개발에 필수적인 이유

TypeScript 프로젝트에서 적절한 타입 정의 없이 JavaScript 라이브러리를 사용하는 것은 TypeScript를 사용하는 이유를 훼손합니다. 인기 있는 유틸리티 라이브러리인 Lodash를 사용하는 간단한 시나리오를 고려해 보겠습니다.

타입 정의가 없는 세계

declaration 파일이 없으면 TypeScript는 lodash가 무엇인지 또는 무엇을 포함하고 있는지 알 수 없습니다. 코드를 컴파일하기 위해 다음과 같은 빠른 수정 방법을 사용하고 싶을 수도 있습니다.

const _: any = require('lodash'); const users = [{ 'user': 'barney' }, { 'user': 'fred' }]; // Autocomplete? No help here. // Type checking? No. Is 'username' the correct property? // The compiler allows this, but it might fail at runtime. _.find(users, { username: 'fred' });

이 경우 _ 변수는 any 타입입니다. 이는 TypeScript에 "이 변수와 관련된 모든 것을 확인하지 마세요."라고 효과적으로 알리는 것입니다. 자동 완성, 인수에 대한 타입 검사, 반환 타입에 대한 확신이 없어 모든 이점을 잃게 됩니다. 이것은 런타임 오류의 온상입니다.

타입 정의가 있는 세계

이제 필요한 declaration 파일을 제공할 때 어떤 일이 발생하는지 살펴보겠습니다. 타입을 설치한 후(다음에서 다룰 예정) 경험이 바뀝니다.

import _ from 'lodash'; interface User { user: string; active?: boolean; } const users: User[] = [{ 'user': 'barney' }, { 'user': 'fred' }]; // 1. Editor provides autocompletion for 'find' and other lodash functions. // 2. Hovering over 'find' shows its full signature and documentation. // 3. TypeScript sees that `users` is an array of `User` objects. // 4. TypeScript knows the predicate for `find` on `User[]` should involve `user` or `active`. // CORRECT: TypeScript is happy. const fred = _.find(users, { user: 'fred' }); // ERROR: TypeScript catches the mistake! // Property 'username' does not exist on type 'User'. const betty = _.find(users, { username: 'betty' });

차이는 밤과 낮입니다. 완벽한 타입 안전성, 툴링을 통한 우수한 개발자 경험, 잠재적인 버그의 극적인 감소를 얻습니다. 이것이 TypeScript로 작업하는 전문적인 표준입니다.

타입 정의를 찾는 계층 구조

그렇다면 좋아하는 라이브러리에 대한 이러한 마법 같은 .d.ts 파일을 어떻게 얻을 수 있을까요? 광범위한 시나리오를 다루는 잘 확립된 프로세스가 있습니다.

1단계: 라이브러리가 자체 타입을 번들로 제공하는지 확인

가장 좋은 시나리오는 라이브러리가 TypeScript로 작성되었거나 유지 관리자가 동일한 패키지 내에서 공식 declaration 파일을 제공하는 경우입니다. 이는 최신, 잘 유지 관리되는 프로젝트에서 점점 더 일반화되고 있습니다.

확인 방법:

1. 평소와 같이 라이브러리를 설치합니다. npm install axios
2. node_modules/axios에서 라이브러리 폴더 안을 살펴보세요. .d.ts 파일이 보이나요?
3. 라이브러리의 package.json 파일에서 "types" 또는 "typings" 필드를 확인하세요. 이 필드는 기본 declaration 파일을 직접 가리킵니다. 예를 들어 Axios의 package.json에는 "types": "index.d.ts"가 포함되어 있습니다.

이러한 조건이 충족되면 완료된 것입니다! TypeScript는 이러한 번들 타입을 자동으로 찾아 사용합니다. 추가 조치가 필요하지 않습니다.

2단계: DefinitelyTyped 프로젝트(@types)

자체 타입을 번들로 제공하지 않는 수천 개의 JavaScript 라이브러리에 대해 글로벌 TypeScript 커뮤니티는 놀라운 리소스인 DefinitelyTyped를 만들었습니다.

DefinitelyTyped는 엄청난 수의 JavaScript 패키지에 대한 고품질 declaration 파일을 호스팅하는 GitHub의 중앙 집중식, 커뮤니티 관리 리포지토리입니다. 이러한 정의는 @types 범위에서 npm 레지스트리에 게시됩니다.

사용 방법:

lodash와 같은 라이브러리가 자체 타입을 번들로 제공하지 않으면 해당 @types 패키지를 개발 종속성으로 설치하면 됩니다.

npm install --save-dev @types/lodash

명명 규칙은 간단하고 예측 가능합니다. package-name이라는 패키지의 경우 해당 타입은 거의 항상 @types/package-name에 있습니다. npm 웹사이트 또는 DefinitelyTyped 리포지토리에서 사용 가능한 타입을 검색할 수 있습니다.

왜 --save-dev일까요? declaration 파일은 개발 및 컴파일 중에만 필요합니다. 런타임 코드를 포함하지 않으므로 최종 프로덕션 번들에 포함되어서는 안 됩니다. devDependency로 설치하면 이러한 분리가 보장됩니다.

3단계: 타입이 존재하지 않을 때 - 직접 작성

타입을 번들로 제공하지 않고 DefinitelyTyped에도 없는 오래된 틈새 또는 내부 개인 라이브러리를 사용하는 경우는 어떻게 될까요? 이 경우 소매를 걷어붙이고 직접 declaration 파일을 만들어야 합니다. 이것이 위협적으로 들릴 수 있지만 간단하게 시작하여 필요에 따라 더 많은 세부 정보를 추가할 수 있습니다.

빠른 수정: 약식 주변 모듈 Declaration

적절한 타이핑 전략을 파악하는 동안 오류 없이 프로젝트를 컴파일하기만 하면 되는 경우가 있습니다. 프로젝트에서 파일(예: declarations.d.ts 또는 types/global.d.ts)을 만들고 약식 declaration을 추가할 수 있습니다.

// in a .d.ts file declare module 'some-untyped-library';

이것은 TypeScript에 "저를 믿으세요. 'some-untyped-library'라는 모듈이 존재합니다. 그것에서 가져온 모든 것을 any 타입으로 취급하세요."라고 알려줍니다. 이것은 컴파일러 오류를 침묵시키지만 논의한 바와 같이 해당 라이브러리에 대한 모든 타입 안전성을 희생합니다. 이것은 임시 패치이지 장기적인 해결책이 아닙니다.

기본 사용자 지정 Declaration 파일 만들기

더 나은 접근 방식은 실제로 사용하는 라이브러리 부분에 대한 타입을 정의하기 시작하는 것입니다. `string-utils`라는 단일 함수를 내보내는 간단한 라이브러리가 있다고 가정해 보겠습니다.

// In node_modules/string-utils/index.js module.exports.capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);

프로젝트 루트의 전용 `types` 디렉터리에 string-utils.d.ts 파일을 만들 수 있습니다.

// In my-project/types/string-utils.d.ts declare module 'string-utils' { export function capitalize(str: string): string; // You could add other function definitions here as you use them // export function slugify(str: string): string; }

이제 TypeScript에 사용자 지정 타입 정의를 찾을 위치를 알려야 합니다. tsconfig.json에서 이를 수행합니다.

{ "compilerOptions": { // ... other options "baseUrl": ".", "paths": { "*": ["types/*"] } } }

이 설정으로 import { capitalize } from 'string-utils'를 수행하면 TypeScript가 사용자 지정 declaration 파일을 찾아 정의한 타입 안전성을 제공합니다. 라이브러리의 더 많은 기능을 사용함에 따라 이 파일을 점차적으로 빌드할 수 있습니다.

더 자세히 알아보기: Declaration 파일 작성

declaration 파일을 작성하거나 읽을 때 접하게 될 몇 가지 고급 개념을 살펴보겠습니다.

다양한 종류의 내보내기 Declaration

JavaScript 모듈은 다양한 방식으로 항목을 내보낼 수 있습니다. declaration 파일은 라이브러리의 내보내기 구조와 일치해야 합니다.

• 명명된 내보내기: 이것이 가장 일반적입니다. 위에서 `export function capitalize(...)`와 함께 보았습니다. 상수, 인터페이스 및 클래스도 내보낼 수 있습니다.

declare module 'my-lib' { export const version: string; export interface Options { retries: number; } export function doSomething(options: Options): Promise; }

• 기본 내보내기: `export default`를 사용하는 라이브러리의 경우.

declare module 'my-default-lib' { // For a function default export export default function myCoolFunction(): void; // For an object default export // const myLib = { name: 'lib', version: '1.0' }; // export default myLib; }

• UMD 전역 변수: <script> 태그를 통해 브라우저에서 작동하도록 설계된 이전 라이브러리의 경우 종종 전역 `window` 객체에 연결됩니다. 이러한 전역 변수를 declaration할 수 있습니다.

// Declares a global variable '$' of a certain type declare var $: JQueryStatic;

• `export =` 및 `import = require()`: 이 구문은 `module.exports = ...`를 사용하는 이전 CommonJS 모듈용입니다. 예를 들어 라이브러리가 `module.exports = myClass;`를 수행하는 경우.

// in my-class.d.ts declare class MyClass { constructor(name: string); } export = MyClass; // in your app.ts import MyClass = require('my-class'); const instance = new MyClass('test');

최신 ES 모듈에서는 덜 일반적이지만 여전히 널리 사용되는 많은 이전 Node.js 패키지와의 호환성에 매우 중요합니다.

모듈 확장: 기존 타입 확장

가장 강력한 기능 중 하나는 모듈 확장(declaration 병합이라고도 함)입니다. 이를 통해 다른 패키지의 declaration 파일에 정의된 기존 인터페이스에 속성을 추가할 수 있습니다. 이는 Express 또는 Fastify와 같은 플러그인 아키텍처가 있는 라이브러리에 매우 유용합니다.

Express에서 `Request` 객체에 `user` 속성을 추가하는 미들웨어를 사용하고 있다고 상상해 보세요. 확장이 없으면 TypeScript는 `user`가 `Request`에 존재하지 않는다고 불평합니다.

다음은 이 새 속성에 대해 TypeScript에 알리는 방법입니다.

// in your types/express.d.ts file // We must import the original type to augment it import { UserProfile } from './auth'; // Assuming you have a UserProfile type // Tell TypeScript we're augmenting the 'express-serve-static-core' module declare module 'express-serve-static-core' { // Target the 'Request' interface inside that module interface Request { // Add our custom property user?: UserProfile; } }

이제 애플리케이션 전체에서 Express `Request` 객체는 선택적 `user` 속성으로 올바르게 타입이 지정되고 완벽한 타입 안전성 및 자동 완성을 얻을 수 있습니다.

Triple-Slash 지시문

때로는 세 개의 슬래시(///)로 시작하는 .d.ts 파일의 맨 위에 주석이 표시될 수 있습니다. 이것들은 컴파일러 지침 역할을 하는 트리플 슬래시 지시문입니다.

• /// <reference types="..." />: 이것이 가장 일반적인 것입니다. 다른 패키지의 타입 정의를 종속성으로 명시적으로 포함합니다. 예를 들어 WebdriverIO 플러그인에 대한 타입에는 자체 타입이 핵심 WebdriverIO 타입에 따라 다르기 때문에 /// <reference types="webdriverio" />가 포함될 수 있습니다.
• /// <reference path="..." />: 이는 동일한 프로젝트 내의 다른 파일에 대한 종속성을 declaration하는 데 사용됩니다. 더 오래된 구문이며 ES 모듈 가져오기로 대체되었습니다.

Declaration 파일 관리 모범 사례

1. 번들 타입 선호: 라이브러리 중에서 선택할 때 TypeScript로 작성되었거나 자체 공식 타입 정의를 번들로 제공하는 라이브러리를 선호합니다. 이는 TypeScript 생태계에 대한 약속을 나타냅니다.
2. @types를 devDependencies에 유지: 항상 --save-dev 또는 -D로 @types 패키지를 설치합니다. 프로덕션 코드에는 필요하지 않습니다.
3. 버전 정렬: 일반적인 오류의 원인은 라이브러리 버전과 @types 버전 간의 불일치입니다. 라이브러리의 주요 버전 업그레이드(예: v2에서 v3로)는 API에 호환성이 손상되는 변경 사항이 있을 가능성이 높으며 이는 @types 패키지에 반영되어야 합니다. 동기화 상태를 유지하십시오.
4. tsconfig.json을 사용하여 제어: tsconfig.json의 typeRoots 및 types 컴파일러 옵션을 사용하면 TypeScript가 declaration 파일을 찾는 위치를 세밀하게 제어할 수 있습니다. typeRoots는 컴파일러에 확인할 폴더를 알려주고(기본적으로 ./node_modules/@types임) types를 사용하면 포함할 타입 패키지를 명시적으로 나열할 수 있습니다.
5. 다시 기여: 타입이 없는 라이브러리에 대한 포괄적인 declaration 파일을 작성한 경우 DefinitelyTyped 프로젝트에 기여하는 것을 고려해 보세요. 이것은 글로벌 개발자 커뮤니티에 환원하고 수천 명의 다른 사람들을 돕는 환상적인 방법입니다.

결론: 타입 안전성의 숨겨진 영웅

TypeScript Declaration 파일은 JavaScript의 역동적이고 광범위한 세계를 강력하고 타입 안전한 개발 환경에 원활하게 통합할 수 있도록 하는 숨겨진 영웅입니다. 이는 도구에 권한을 부여하고 수많은 버그를 방지하며 코드베이스를 더욱 탄력적이고 자체 문서화하도록 만드는 중요한 연결 고리입니다.

.d.ts 파일을 찾고, 사용하고, 심지어 직접 만드는 방법을 이해함으로써 컴파일러 오류를 수정하는 것뿐만 아니라 전체 개발 워크플로를 향상시키고 있습니다. TypeScript와 풍부한 JavaScript 라이브러리 생태계의 잠재력을 최대한 활용하여 더 나은 안정적인 소프트웨어를 전 세계 사용자에게 제공하는 강력한 시너지 효과를 창출하고 있습니다.