TypeScript가 느려지는 N가지 이유: 컴파일 성능 최적화 실전 가이드

TypeScript 프로젝트의 규모가 커지면서 어느 날 문득 깨닫게 됩니다. 코드를 수정하고 저장할 때마다 VS Code의 타입 추론(IntelliSense)이 버벅이고, tsc 빌드 시간은 하염없이 늘어납니다. 이는 단순한 불편함을 넘어, 우리의 소중한 개발 생산성과 흐름을 끊어버리는 심각한 문제로 이어집니다.

느린 컴파일은 왜 발생하며, 우리는 이 문제를 어떻게 해결할 수 있을까요?

오늘은 TypeScript의 컴파일 타임 성능을 저하시키는 주범들을 심층 분석하고, 복잡한 타입 연산부터 프로젝트 설정까지 아우르는 구체적이고 실용적인 최적화 전략을 자세히 알아보겠습니다.

1. 왜 컴파일 성능이 중요한가?: 단순한 속도 그 이상의 문제

느린 컴파일은 단순히 '기다리는 시간'이 길어지는 것만을 의미하지 않습니다.

• 지연되는 피드백: 코드 에디터에서 타입 오류를 확인하는 데 몇 초씩 걸린다면, 실시간으로 코드를 수정하고 검증하는 TypeScript의 가장 큰 장점이 사라집니다.
• 인지 부하 증가: 잦은 버벅임은 개발자의 집중력을 흩트리고, 문제 해결의 흐름을 방해하여 불필요한 인지 부하를 유발합니다.
• CI/CD 시간 증가: 로컬 개발 환경뿐만 아니라, 코드를 빌드하고 배포하는 CI/CD 파이프라인의 시간도 길어져 전체 팀의 생산성에 영향을 미칩니다.

결국 컴파일 성능은 곧 개발자 경험(DX, Developer Experience) 과 직결되는 핵심적인 요소입니다.

---

2. 주범 1: 과도하게 복잡한 타입 연산

컴파일 성능 저하의 가장 흔한 원인은 필요 이상으로 복잡하고 광범위한 타입 연산입니다.

가. 거대한 유니온과 Mapped Types의 함정

Mapped Types는 매우 강력하지만, 수천 개의 키를 가진 거대한 객체 타입에 직접 적용하는 순간 컴파일러의 악몽이 시작됩니다.

😩 Bad: 모든 경우의 수를 미리 계산하는 접근법

수백 개의 아이콘 정보를 담은 객체를 기반으로, 모든 아이콘을 boolean prop으로 받을 수 있는 Icon 컴포넌트를 만든다고 가정해 봅시다.

// icons.ts - 500+개의 아이콘이 있다고 가정
export const ICONS = {
  add: '<svg>...</svg>',
  arrowDown: '<svg>...</svg>',
  // ...
  wallet: '<svg>...</svg>',
};
export type IconName = keyof typeof ICONS; // "add" | "arrowDown" | ...

// Bad: 500개 이상의 유니온에 대해 Mapped Type을 실행
// 컴파일러는 Icon 컴포넌트가 사용될 때마다 이 거대한 타입을 계산해야 한다.
type IconProps = {
  [K in IconName]?: boolean; // 500번 이상의 연산 발생
};

function Icon(props: IconProps) {
  // ...
}

이 방식은 Icon 컴포넌트가 사용될 때마다 500개가 넘는 옵셔널 프로퍼티를 가진 거대한 타입을 계산하게 만듭니다. 실제로는 한두 개의 아이콘만 사용하는데도 말이죠.

😊 Good: 제네릭을 통한 '지연' 및 '추론' 활용

더 나은 접근법은 사용 시점에 필요한 만큼만 타입을 추론하도록 제네릭을 활용하는 것입니다. 타입 계산의 시점을 '미리'에서 '필요할 때'로 미루는 전략입니다.

// Good: 제네릭을 사용해 실제 전달된 props만 타입으로 추론
type IconProps<T extends IconName> = {
  [K in T]?: boolean;
};

function Icon<T extends IconName>(props: IconProps<T>) {
  // ...
}

// 사용 시점에는 "add", "wallet" 두 개의 키에 대해서만 타입 연산이 일어난다.
<Icon add wallet />;

이처럼 제네릭을 사용하면, TypeScript는 Icon 컴포넌트가 실제로 사용될 때 전달된 프롭(add, wallet)만을 기반으로 타입을 계산하므로 컴파일 부담이 극적으로 줄어듭니다.

나. 조건부 타입(Conditional Types)의 의도치 않은 분배

조건부 타입이 제네릭 유니온 타입을 만나면, 각 유니온 멤버에 대해 개별적으로 타입을 계산하는 분배 법칙(Distributive Conditional Types) 이 적용됩니다. 이는 때로 성능 저하와 의도치 않은 결과를 초래합니다.

😩 Bad: 분배 법칙으로 인해 타입이 너무 넓어지는 경우

API 라우트 경로("/users", "/users/:id") 중 파라미터가 포함된 경로만 추출하는 유틸리티 타입을 만든다고 가정해 봅시다.

type Routes = "/users" | "/users/:id" | "/posts" | "/posts/:id";

// `:id`가 string의 서브타입이므로 모든 Routes가 string으로 변환되어 버린다.
type RoutesWithParams<T> = T extends `/${string}/:id` ? T : never;

// 의도: "/users/:id" | "/posts/:id"
// 실제 결과: string
// 왜? ("users" extends `...`) | ("/users/:id" extends `...`) | ... 로 분배되어
// 의도와 다르게 동작하며 불필요한 연산을 수행한다.
type DynamicRoutes = RoutesWithParams<Routes>;

😊 Good: []로 분배 방지하기

유니온 타입 자체를 하나의 단위로 검사하고 싶다면, 타입을 대괄호([])로 감싸 튜플로 만들어 분배를 방지할 수 있습니다.

// Good: [T] extends [U] 형태로 감싸 분배를 방지한다.
type RoutesWithParams<T> = [T] extends [`/${string}/:id`] ? T : never;

// 이제 유니온 전체가 하나의 단위로 취급되어 의도대로 동작하지 않는다.
// 이런 경우엔 다른 접근이 필요하지만, 분배 방지 원리는 동일하다.

// 더 적절한 분배 방지 예시
type Wrap<T> = [T] extends [any] ? T[] : T;
type T1 = Wrap<string | number>; // 결과: (string | number)[] -> 분배되지 않음

분배 법칙을 이해하고 제어하는 것만으로도 복잡한 타입의 연산 횟수를 크게 줄일 수 있습니다.

다. 재귀 타입(Recursive Types)의 무한 루프

자기 자신을 참조하는 재귀 타입은 매우 강력하지만, 종료 조건이 명확하지 않으면 컴파일러를 무한 루프에 빠뜨려 "Type instantiation is excessively deep and possibly infinite." 에러를 발생시킵니다.

😩 Bad: 종료 조건 없는 무한 재귀

// Bad: 깊이가 깊어지면 무한 루프에 빠질 수 있는 타입
type DeepFlatten<T> = T extends object ? DeepFlatten<T[keyof T]> : T;

😊 Good: 재귀 깊이 제한 장치 추가하기

안전한 재귀 타입을 만들려면, 재귀의 깊이를 추적하고 특정 깊이에 도달하면 연산을 중단하는 '회로 차단기'를 추가해야 합니다.

// Good: 재귀 깊이를 추적하는 Depth 파라미터 추가
type DeepFlatten<T, Depth extends any[] = []> = Depth['length'] extends 10 // 최대 깊이 10으로 제한
  ? T
  : T extends object
  ? DeepFlatten<T[keyof T], [...Depth, any]>
  : T;

---

3. 방어선 구축: tsconfig.json과 프로젝트 설정

복잡한 타입을 수정하기 전에, 간단한 설정 변경만으로도 큰 효과를 볼 수 있습니다.

가. incremental: true

컴파일러가 마지막 컴파일 상태를 .tsbuildinfo 파일에 저장해두고, 다음 컴파일 시 변경된 파일만 다시 검사합니다. 대규모 프로젝트에서 필수적인 옵션입니다.

// tsconfig.json
{
  "compilerOptions": {
    "incremental": true
  }
}

나. skipLibCheck: true

node_modules에 있는 라이브러리들의 타입 선언 파일(.d.ts)에 대한 타입 검사를 건너뜁니다. 라이브러리 타입은 이미 검증되었다고 가정하여 전체 컴파일 시간을 크게 단축시킬 수 있습니다. 대부분의 경우 안전하게 사용할 수 있습니다.

// tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

다. 프로젝트 분리를 통한 효과적인 관리 (references)

거대한 모노레포(Monorepo) 프로젝트의 경우, TypeScript의 프로젝트 레퍼런스(Project References) 기능을 사용하여 프로젝트를 여러 개의 작은 하위 프로젝트로 분리할 수 있습니다. 이렇게 하면 tsc --build 명령을 통해 변경된 하위 프로젝트와 그에 의존하는 프로젝트만 지능적으로 재빌드하여 전체 빌드 시간을 획기적으로 줄일 수 있습니다.

---

결론: 성능은 지속적인 관심의 대상

TypeScript 컴파일 성능은 한번 해결하고 끝나는 문제가 아니라, 프로젝트가 성장함에 따라 지속적으로 관리해야 하는 대상입니다.

느린 컴파일 속도로 고통받고 있다면, 다음의 체크리스트를 따라 프로젝트를 점검해 보세요.

• ✅ 거대 유니온에 Mapped Type을 직접 사용하고 있진 않은가? -> 제네릭으로 지연시키세요.
• ✅ Conditional Type이 의도치 않게 분배되어 복잡한 연산을 유발하는가? -> [T]로 감싸 분배를 방지하세요.
• ✅ 종료 조건이 불분명한 Recursive Type이 있는가? -> 재귀 깊이 제한 장치를 추가하세요.
• ✅ tsconfig.json에 "incremental": true 와 "skipLibCheck": true 가 설정되어 있는가?
• ✅ 모노레포라면 프로젝트 레퍼런스를 활용해 프로젝트를 분리했는가?

똑똑한 타입 설계와 올바른 프로젝트 설정은 단순히 컴파일 시간을 줄이는 것을 넘어, 우리의 개발 경험을 더욱 쾌적하고 즐겁게 만들어주는 최고의 투자입니다.