🗂️ 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 에러를 뿜어냅니다! 어떡하죠?!"
• 🦁 영호 ( 리드 ): "영철 님, 타입스크립트의 세계에서는 여권(타입 선언)이 없는 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,           // 무조건 켜기. 이거 끌 거면 TS 쓰지 마세요.
    "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 {
  // 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 인터페이스를 확장(Declaration Merging)해 줍니다.

💡 상세 해설:

• 원리 설명: 내장 전역 객체(Window, Document, Array 등)의 타입은 TS 코어 선언 파일에 이미 interface로 등록되어 있습니다. 2장에서 배운 '선언 병합' 원리에 따라, 우리가 declare global 스코프 안에서 동일한 이름의 Window 인터페이스를 다시 선언하고 살을 붙여주면, 컴파일러가 알아서 하나로 합쳐줍니다.
• 오답 피드백: "영철 님, 언제까지 (window as any) 같은 구식 해킹으로 코드를 오염시킬 건가요? 브릿지 객체도 엄연한 회사 자산입니다. 당당하게 글로벌 시민(타입)권을 부여해 주세요."
• 📌 핵심 기억법: 내 맘대로 브라우저를 개조하고 싶다면? declare global과 interface Window를 합체해라!

🐣 영철이의 퇴근 일기

💡 "규칙은 우리를 억압하는 게 아니라, 뒤통수를 맞는 런타임 에러로부터 우리를 지켜주는 가장 단단한 방어벽이다."

그동안 tsconfig.json은 그냥 React 깔면 딸려오는 의미 없는 장식품인 줄 알았는데, 그게 내 VScode의 모든 지능을 통제하는 중앙 관제탑이었다니.
게다가 항상 빨간 줄 뿜어내던 외부 구형 스크립트들을 내 손으로 declare module 해서 얌전하게 만들고 나니까, 마치 내가 타입스크립트를 이겨 낸(!) 것 같은 승리감마저 든다.
이제 더 이상 window as any 같은 잔여물은 내 코드에 남기지 않겠다. 내일 바로 브릿지 메서드들 global.d.ts 에 전부 타이핑해서 영호 리드 님한테 리뷰받아야지. 오늘 퇴근 발걸음은 유난히 가볍다!