---
id: wiki-2026-0508-대규모-typescript-프로젝트의-컴파일-성능-최적화
title: 대규모 TypeScript 프로젝트의 컴파일 성능 최적화
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [TypeScript Performance, tsc Optimization, Project References]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [typescript, performance, monorepo, build, project-references]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript 5.x
  framework: tsc/esbuild/swc/Turbo
---

# 대규모 TypeScript 프로젝트의 컴파일 성능 최적화

## 매 한 줄
> **"매 Type-check separately, 매 transpile fast"**. 매 TS 의 compile = 매 type-check (slow) + 매 emit (cheap if no checks). 매 2026 stack 은 매 swc/esbuild 로 매 emit 하고 매 tsc --noEmit 로 매 check, 매 monorepo 는 매 project references + Turbo/Nx remote cache.

## 매 핵심

### 매 병목의 정체
- 매 type 의 transitive expansion — 매 generic / conditional / mapped 의 폭발.
- 매 module 의 graph traversal — 매 너무 wide 한 barrel re-export.
- 매 d.ts 의 generation — 매 declaration emit 의 expensive.
- 매 tsserver 의 IDE — 매 incremental 의 cold start.

### 매 두 축의 전략
1. **매 type-check 의 빈도 ↓**: 매 PR 시 1회, 매 dev 는 IDE/incremental.
2. **매 emit 의 분리**: 매 swc/esbuild 가 매 emit, 매 tsc 는 매 noEmit.

### 매 Monorepo 의 split
- 매 Project references (`composite: true`) — 매 incremental d.ts 캐시.
- 매 `--build --incremental` — 매 changed graph 만 매 recompile.
- 매 Turborepo / Nx — 매 task graph + 매 remote cache (S3, R2).

## 패턴

### tsconfig 의 전략
```json
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    "skipLibCheck": true,
    "isolatedModules": true,
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "noEmit": true
  }
}
```

### Project references (monorepo root)
```json
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/api" },
    { "path": "./packages/web" }
  ]
}
```

### Per-package composite
```json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist"
  },
  "references": [{ "path": "../core" }]
}
```

### swc 로 emit + tsc 로 check
```bash
# 매 dev — fast emit
swc src -d dist --strip-leading-paths

# 매 CI — 별도 type check
tsc -b --noEmit
```

### Generic 의 explosion 회피
```typescript
// 매 Bad — 매 conditional + mapped 의 nested
type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
};

// 매 Better — 매 explicit boundary
type PartialOnly<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
```

### Barrel export 의 tree-shaking
```typescript
// 매 Bad — 매 barrel
// index.ts
export * from "./a";
export * from "./b";
export * from "./c";

// 매 Better — 매 named, 매 specific paths in consumer
// consumer
import { a } from "@pkg/a";
import { b } from "@pkg/b";
```

### tsc trace 로 병목 발견
```bash
tsc -p . --generateTrace ./trace
# 매 chrome://tracing 에서 trace.json 로드
# 매 hot type 의 식별
```

### Turborepo cache
```json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".tsbuildinfo"],
      "cache": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": [],
      "cache": true
    }
  },
  "remoteCache": { "enabled": true }
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 단일 package, 매 small | tsc 직접, 매 incremental |
| 매 monorepo 5+ pkg | Project references + Turborepo |
| 매 dev iteration speed 절실 | swc/esbuild emit + tsc noEmit (CI) |
| 매 IDE 가 slow | `skipLibCheck`, 매 type complexity ↓, 매 split |
| 매 type 의 deep generic 폭발 | --generateTrace 로 hot type 식별 |

**기본값**: 매 monorepo = 매 Turborepo + project references + swc emit + tsc --build --noEmit.

## Graph
- 부모: [[TypeScript]]
- 변형: [[Project References]] · [[Incremental Build]]
- 응용: [[Turborepo]] · [[Nx]] · [[swc]] · [[esbuild]]

## LLM 활용
**언제**: 매 tsconfig 작성/리뷰, 매 monorepo 구조 설계, 매 trace 분석, 매 generic 단순화.
**언제 X**: 매 production runtime tuning (TS 의 compile 매 vs runtime 의 별개).

## 안티패턴
- **매 `any` 의 남발 = type-check 빠름**: 매 진짜 problem 의 mask.
- **매 Single huge tsconfig in monorepo**: 매 incremental 의 무력화.
- **매 Wide barrel re-export**: 매 graph 폭발.
- **매 No `skipLibCheck`**: 매 d.ts 매 깊이 들어가 매 cost 폭발.
- **매 Decorator + reflect-metadata**: 매 type 의 매우 expensive.

## 검증 / 중복
- Verified: TypeScript Wiki "Performance", microsoft/TypeScript#XX 이슈, Turborepo / swc docs.
- 신뢰도 A.

## Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — TS perf 패턴 (project refs, swc, trace, Turbo) 작성 |
