🗂️ 06. 선언 파일과 설정: 레거시 JS를 우아하게 품어라

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 10분(전체) / 핵심 파트만: 6분

🗺️ 이 문서의 흐름
[tsconfig.json의 두 가지 핵심 축] → [.d.ts의 존재 이유] → [글로벌 공간 침투하기(declare global)]

🎯 이 문서를 다 읽으면 할 수 있는 것

• strict 모드의 진정한 의미를 이해하고 프로젝트 설정의 이유를 설명할 수 있다.
• 타겟(Target)과 모듈(Module) 설정이 왜 프론트엔드 환경에서 나눠지는지 이해한다.
• 타입 지원이 없는 사내 구형 라이브러리나 윈도우(Window) 객체를 자유자재로 타입 확장할 수 있다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 프로젝트 경계를 정리하는 중 ): "리드 님! 회사에 예전부터 내려오는 jQuery 기반 애니메이션 스크립트(youngsoo-magic.js)를 가져다 쓰려는데, import 하자마자 VScode가 Could not find a declaration file for module 에러를 보여줍니다. 타입이 없는 코드도 프로젝트에 안전하게 들여올 방법이 있을까요?"
• 🦁 영호 ( 리드 ): "영철 님, 타입스크립트는 import한 모듈의 타입 선언을 찾아야 안전하게 검사할 수 있어요. 타입이 없는 JS 파일이라도 우리가 .d.ts로 최소 계약을 적어줄 수 있죠. 그리고 그 선언을 어디까지 포함할지 정하는 기준표가 tsconfig.json입니다. 오늘 그 두 가지 통제권을 쥐어보죠."

🤔 왜 알아야 하는가: '설정'을 두려워하지 말라

보통 주니어 프론트엔드 개발자들은 npx create-next-app이나 vite가 만들어 주는 tsconfig.json을 단 한 번도 열어보지 않고 살살 피해 다닙니다. 무언가 건드리면 큰일 날 것 같기 때문이죠.

하지만 프로젝트를 진행하다 보면 필연적으로 다음과 같은 위기에 봉착합니다.

1. "오픈소스 라이브러리를 깔았는데 타입 정의가 없대..." (npm i @types/xxx 도 안 통함)
2. "인라인 스크립트로 넣어둔 구글 애널리틱스 전역 객체 window.ga를 쓰고 싶은데 TS가 화내..."

이때 설정과 선언 파일의 개념을 모르면, // @ts-ignore 나 as any로 호출부마다 타입 검사를 꺼버리기 쉽습니다. 5년 차의 아키텍처는 이런 예외를 숨기는 대신, 타입이 없는 경계에 팀이 공유할 계약을 붙이는 것에서 시작합니다.

⚙️ 1. tsconfig.json의 뼈대 이해하기

tsconfig.json 옵션은 수십 개가 넘지만, 현업에서 우리가 컨트롤해야 할 핵심 축은 크게 두 가지입니다.

축 A: 컴파일 퀄리티 (엄격함의 정도)

{
  "compilerOptions": {
    "strict": true,           // 신규 프로젝트라면 기본값으로 켜고 시작하기
    "noImplicitAny": true,    // "귀찮아서 any로 놔둔 거 다 잡아낼 거야!"
    "strictNullChecks": true  // "null 이랑 undefined가 들어올 수 있는 가능성 전부 차단해!"
  }
}

🦁 영호의 리뷰 코멘트: "strict: true는 위 옵션들을 다 켜주는 스위치입니다. 구형 JS 프로젝트를 마이그레이션하는 특수한 상황이 아니라면 켜고 시작하는 편이 안전합니다. 느슨한 설정은 당장은 편하지만, 런타임에서 확인해야 할 일이 늘어납니다."

축 B: 타겟과 환경 설정 (어디서 돌릴 것인가)

이 부분이 많은 사람들을 헷갈리게 합니다.

{
  "compilerOptions": {
    // 1. 내가 변환할 최종 JS 문법 수준
    "target": "ES6",
 
    // 2. 모듈 시스템은 뭘 쓸 건가? (CommonJS vs ESNext)
    "module": "ESNext",
 
    // 3. 브라우저에서 돌릴 거야? 노드에서 돌릴 거야? (사용 가능한 내장 객체들)
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
 
    // 번들러(Webpack, Webpack, Vite, Next.js 등)를 쓸 때 필수 옵션
    "moduleResolution": "bundler",
  }
}

프론트엔드(React, Next.js)에서는 사실상 TS 컴파일러(tsc)가 실제로 JS를 변환하여 떨구는(emit) 역할을 하지 않습니다. 변환은 Babel이나 SWC, 에스빌드(esbuild)가 훨씬 빨리 해치웁니다.
따라서 우리는 tsconfig.json을 "VScode의 빨간 줄 검사기 기준표" 정도로 생각하면 맘이 편합니다.

🛂 2. .d.ts 선언 파일: 타입 전용 여권 발급소

영철이의 딜레마로 돌아가 봅시다. 구형 라이브러리에 타입이 없습니다.
타입스크립트는 임포트되는 모듈을 볼 때 항상 그 옆에 짝꿍인 .d.ts (Declaration) 파일이 있는지를 찾습니다.

.d.ts 파일에는 실제 동작하는 자바스크립트 코드(로직)가 단 한 줄도 들어갈 수 없습니다. 오로지 "여기 이런 함수랑 클래스가 있어~" 하고 껍데기만 선언(Declare)해 주는 파일입니다.

영철이의 마술 같은 파일: youngsoo-magic.d.ts

프로젝트 최상단 types 폴더(보통 tsconfig.json의 include에 등록됨)에 빈 파일을 만들고 아래처럼 써주면 어리둥절하던 TS가 갑자기 얌전해집니다.

// types/youngsoo-magic.d.ts
 
// 🦁 영호: "일단 급하니까 저 모듈이 존재한다는 것만 TS한테 신고합시다."
declare module 'youngsoo-magic' {
  // 모듈 내부의 함수나 객체 뼈대를 여기에 대충이라도 묘사해준다.
  export function doMagic(target: string): void;
  export const version: string;
}

이제 import { doMagic } from 'youngsoo-magic' 을 써도 아무 에러가 나지 않습니다. 타입스크립트는 이제 해당 파일에 저런 함수가 있다는 걸 "선언"받았기 때문입니다.

🌍 3. 글로벌 차원 침투: declare global

가장 우아하고 빈번하게 사용되는 스킬입니다.
브라우저에 내장된 window 객체에 영수네 회사가 만든 전역 함수 window.KakaoLogin()을 붙이고 싶습니다.

// 일반 TS 파일
window.KakaoLogin = () => { /* ... */ };
// ❌ 에러: Property 'KakaoLogin' does not exist on type 'Window & typeof globalThis'.

선언 병합(Declaration Merging)의 부활

우리는 2장(Interface vs Type)에서 interface는 똑같은 이름으로 두 번 선언하면 합쳐진다는 것을 배웠습니다. 이를 window 객체에 적용합니다.

// types/global.d.ts
export {}; // 이 파일을 전역 스크립트가 아닌 모듈로 인식시켜 declare global을 안전하게 둔다.
 
declare global {
  // Window 인터페이스를 열고 내 맘대로 확장!
  interface Window {
    KakaoLogin: () => void;
    // 사내 환경 변수 같은 것도 전역으로 넣어둘 수 있다.
    YOUNGSOO_ENV: string;
  }
}

이렇게 하면 프로젝트 어디에서든 window.KakaoLogin()을 호출할 때 자동 완성이 뜨고, 안전하게 사용할 수 있습니다.

📝 마무리 퀴즈

Q1. tsconfig.json의 strict: true 옵션은 무엇을 의미하나요?

✅ 정답: 타입스크립트의 가장 엄격한 타입 검사기 옵션들(noImplicitAny, strictNullChecks 등)을 한꺼번에 켜주는 마스터 스위치입니다.

💡 상세 해설:

• 이 옵션을 켜지 않으면 타입스크립트는 사실상 "타이핑도 할 수 있는 자바스크립트" 수준의 느슨한 언어로 전락합니다.
• 예기치 못한 런타임 Null 에러를 막는 strictNullChecks의 방패를 잃게 되므로, 신규 프로젝트라면 무조건 true로 설정하고 시작하는 것이 5년 차의 철칙입니다.

Q2. 순수한 .d.ts 선언 파일 안에는 어떤 코드를 작성할 수 "없는"가요?

✅ 정답: 실제로 데이터를 조작하거나 함수가 동작하는 '구현부(Implementation)' 코드는 작성할 수 없습니다. (예: function add(a:number) { return a + 1 } 같이 중괄호로 실행되는 코드 불가)

💡 상세 해설:

• .d.ts는 타입 선언 전용 파일입니다. 실제 동작하는 자바스크립트로 변환(Emit)되지 않는 투명한 파일입니다.
• 오직 interface, type, declare module, declare var 등 뼈대(Signature)만을 선포하는 역할만 수행합니다.

Q3. [영철이의 테스트 타임: 전역 오염 딜레마] 영철이가 인프라팀의 요청으로, 모바일 앱에서 웹뷰(WebView)에 주입해주는 브릿지(Bridge) 객체 window.AppBridge.close()를 호출해야 합니다. VScode는 계속 window에 AppBridge가 없다고 화를 내고, 영철이는 또 체념하며 (window as any).AppBridge.close()를 씁니다. 퇴근 전 이 코드를 리뷰한 영호 리드는 어떤 해법을 제시할까요?

✅ 정답: global.d.ts 파일을 만들고 declare global { interface Window { AppBridge: { close: () => void } } }로 Window 인터페이스를 확장한다.

💡 상세 해설:

• 원리 설명: 내장 전역 객체(Window, Document, Array 등)의 타입은 TS 코어 선언 파일에 이미 interface로 등록되어 있습니다. 2장에서 배운 '선언 병합' 원리에 따라, 우리가 declare global 스코프 안에서 동일한 이름의 Window 인터페이스를 다시 선언하고 살을 붙여주면, 컴파일러가 알아서 하나로 합쳐줍니다.
• (window as any)는 호출부마다 타입 검사를 포기하게 만들지만, global.d.ts의 선언 병합은 프로젝트 전체에 공통 계약을 제공합니다.
• 파일이 모듈로 인식되도록 export {};를 두고, 실제 구현이 아니라 타입 껍데기만 선언해야 합니다.
• 핵심은 전역 객체를 "몰래 쓰기"가 아니라, 팀이 공유하는 선언 파일에 명시적인 계약으로 등록하는 것입니다.

🐣 영철이의 퇴근 일기

오늘은 tsconfig.json과 .d.ts가 숨겨진 설정 파일이 아니라 팀의 타입 계약이라는 걸 배웠다. 특히 타입 없는 레거시 스크립트를 만났을 때 @ts-ignore로 지나가는 건 당장의 침묵일 뿐, 다음 사람이 어디까지 믿어도 되는지 알 수 없게 만든다.

declare module은 모듈의 여권을 만들어주는 일이고, declare global은 전역 객체에 팀이 합의한 속성을 등록하는 일이다. 둘 다 실제 구현을 만드는 게 아니라, 이미 존재하는 런타임 코드의 모양을 TS에게 설명하는 작업이었다.

💡 "선언 파일은 빨간 줄을 숨기는 종이가 아니라, 타입이 없는 경계에 붙이는 계약서다."

내일은 웹뷰 브릿지 호출부에서 (window as any)를 검색해 global.d.ts로 옮길 수 있는지 확인해야겠다. 설정을 고칠 때는 왜 이 옵션이 필요한지도 PR 설명에 남겨야 팀이 같은 기준으로 유지할 수 있다.