TypeScript 6.0 마이그레이션 실전 가이드: 7.0 Go 컴파일러 대비 지금 팀이 고정해야 할 설정

1. 문제 정의

TypeScript 6.0이 2026년 3월 17일 정식 출시되면서 기존 프로젝트에서 빌드 실패가 속출하고 있다. 핵심 원인은 strict 모드 기본 활성화, ES modules(esnext) 기본 해상도, es2025 타겟 기본값 등 주요 설정이 변경되었기 때문이다.

이 글이 해결하는 문제:

• TypeScript 6.0 업그레이드 후 tsc 빌드가 갑자기 실패하는 팀
• ES5/CommonJS/AMD 레거시 코드베이스를 유지해야 하는 프로젝트
• TypeScript 7.0(Go 컴파일러) 대비 마이그레이션 로드맵이 필요한 기술 리더

적용 범위: Node.js 18+ 환경, 모노레포/멀티패키지 구조, Next.js/React/Nest.js 등 모던 프레임워크 사용 프로젝트

비적용 범위: ES5 타겟이 필수인 IE11 지원 프로젝트(별도 트랜스파일러 필요), Deno/Bun 전용 프로젝트

2. 근거 및 비교

TypeScript 6.0의 핵심 변경사항을 5.x 버전과 비교하면 다음과 같다:

설정	TS 5.x 기본값	TS 6.0 기본값	마이그레이션 영향도
strict	false	true	높음 - implicit any 오류 급증
module	commonjs	esnext	높음 - require() 구문 오류
moduleResolution	node (node10)	nodenext/bundler	중간 - 경로 해상도 변경
target	es5/es2015	es2025	낮음 - 최신 브라우저 대상
noUncheckedSideEffectImports	false	true	중간 - polyfill import 점검 필요

마이그레이션 접근법 비교:

접근법	장점	단점	추천 상황
점진적 마이그레이션	리스크 분산, 팀 학습 곡선 완화	중간 상태 관리 복잡	대규모 레거시 프로젝트
일괄 전환 (Big Bang)	깔끔한 전환, 중간 상태 없음	한 번에 많은 오류 수정 필요	소규모 프로젝트, 테스트 커버리지 높은 코드베이스
ignoreDeprecations 활용	즉시 TS 6.0 사용, 점진적 수정	TS 7.0에서 강제 마이그레이션	시간 부족, TS 7.0까지 여유 있는 팀

3. 단계별 실행 방법

Step 1: RC 버전으로 사전 테스트 (1-2시간)

# 별도 브랜치에서 테스트
git checkout -b ts6-migration
npm install -D typescript@rc

# 빌드 테스트
npx tsc --noEmit 2>&1 | tee ts6-errors.log

# 오류 유형별 카운트
grep -oP "error TS\d+" ts6-errors.log | sort | uniq -c | sort -rn | head -20

Step 2: tsconfig.json 호환 설정 추가

{
  "compilerOptions": {
    // 기존 동작 유지를 위한 명시적 설정
    "strict": false,                    // 점진적 활성화 권장
    "module": "commonjs",               // 또는 "nodenext" for ESM
    "moduleResolution": "nodenext",     // node10 제거됨
    "target": "es2022",                 // 필요시 낮은 버전 유지
    "noUncheckedSideEffectImports": false,
    
    // 사용 중단 경고 무시 (TS 7.0 전까지만 유효)
    "ignoreDeprecations": "6.0",
    
    // @types 명시적 지정 (자동 포함 제거됨)
    "types": ["node", "jest"]
  }
}

Step 3: Import Assertions → Import Attributes 변환

// ❌ 6.0에서 오류
import data from './config.json' assert { type: 'json' };

// ✅ 올바른 문법
import data from './config.json' with { type: 'json' };

일괄 변환 명령:

# sed로 일괄 변환
find src -name "*.ts" -exec sed -i 's/assert {/with {/g' {} +

Step 4: strict 모드 점진적 활성화

{
  "compilerOptions": {
    "strict": false,
    // 개별 플래그로 점진 활성화
    "noImplicitAny": true,           // 1단계
    "strictNullChecks": true,        // 2단계
    "strictFunctionTypes": true,     // 3단계
    "strictBindCallApply": true,     // 4단계
    "strictPropertyInitialization": true, // 5단계
    "noImplicitThis": true,          // 6단계
    "alwaysStrict": true             // 7단계 → strict: true 전환
  }
}

Step 5: 의존성 업데이트

# @types/node 업데이트 필수
npm install -D @types/node@latest

# eslint-typescript 플러그인
npm install -D @typescript-eslint/parser@latest @typescript-eslint/eslint-plugin@latest

# 호환성 검증
npm ls typescript @types/node

Step 6: CI/CD 파이프라인 업데이트

# .github/workflows/ci.yml
jobs:
  build:
    strategy:
      matrix:
        typescript: ['5.8', '6.0']  # 병렬 테스트
    steps:
      - run: npm install -D typescript@${{ matrix.typescript }}
      - run: npm run typecheck
      - run: npm run build

4. 실수/함정(Pitfalls)

함정 1: moduleResolution: node 제거

증상: error TS2834: Relative import paths need explicit file extensions

원인: moduleResolution: "node" (또는 "node10") 옵션이 완전히 제거됨

해결:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "nodenext"  // 또는 "bundler"
  }
}

// ESM 프로젝트라면 확장자 명시
import { util } from './utils.js';  // .js 확장자 필수

함정 2: @types 자동 포함 제거

증상: Cannot find name 'process', Cannot find name 'Buffer'

원인: node_modules/@types 자동 포함이 비활성화됨

해결:

{
  "compilerOptions": {
    "types": ["node", "jest", "webpack-env"]  // 명시적 선언
  }
}

함정 3: namespace → module 키워드 오류

증상: error TS1194: Export declarations are not permitted in a namespace

원인: 레거시 module MyLib { } 문법이 namespace로 강제 변환

해결:

// ❌ 레거시 (에러)
module MyLib {
  export function hello() {}
}

// ✅ 올바른 문법
namespace MyLib {
  export function hello() {}
}

함정 4: downlevelIteration 플래그 오류

증상: error TS5107: Option 'downlevelIteration' has no effect

원인: target: es2025 기본값에서 불필요해진 플래그

해결: tsconfig.json에서 해당 옵션 제거

함정 5: stableTypeOrdering으로 인한 빌드 속도 저하

증상: 타입 체크 속도 25% 저하

원인: TS 7.0 호환을 위한 --stableTypeOrdering 플래그 사용 시

해결: 개발 환경에서는 비활성화, CI에서만 활성화

# package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:strict": "tsc --noEmit --stableTypeOrdering"
  }
}

5. 실행 체크리스트

배포 전 필수 확인 항목:

• ☐ npx tsc --noEmit 오류 0건 확인
• ☐ moduleResolution이 nodenext 또는 bundler로 설정됨
• ☐ types 배열에 필요한 @types 패키지 명시됨
• ☐ Import assertions이 Import attributes로 변환됨 (assert → with)
• ☐ strict: false인 경우 개별 strict 플래그 점진 활성화 계획 수립됨
• ☐ CI 파이프라인에서 TS 5.8 + 6.0 병렬 테스트 구성됨
• ☐ ignoreDeprecations: "6.0" 사용 시 TS 7.0 마이그레이션 일정 확보됨

완료 기준(Definition of Done): npm run build가 TS 6.0에서 경고/오류 0건으로 통과하고, 모든 테스트가 기존과 동일하게 성공한다.

6. 참고자료(References)

• TypeScript 6.0 RC 공식 발표 - Microsoft DevBlogs (2026년 3월)
• TypeScript 6.0 Beta 출시 및 주요 변경사항 - InfoQ (2026년 2월)
• TypeScript 6.0 RC 마이그레이션 가이드 - ReactLibraries (2026년 3월)
• TS 6.0.1 RC 빌드 깨지지 않게 설치하는 법 - NTCompatible (2026년 3월)
• TypeScript 7.0 Go 컴파일러 비공식 빌드 - GitHub (2026년)

7. 작성자 관점(Author Viewpoint)

추천: 대부분의 팀에게 점진적 마이그레이션 + ignoreDeprecations: "6.0" 병행을 권장한다. 이유는 다음과 같다:

• TS 7.0 (Go 컴파일러)이 2026년 여름에 출시 예정이므로, 6.0에서 무리하게 모든 deprecated 옵션을 제거할 필요가 없다
• strict: true를 한 번에 활성화하면 대규모 프로젝트에서 수천 개의 오류가 발생할 수 있다. 개별 플래그로 단계적 적용이 현실적이다
• CI에서 TS 5.8과 6.0을 병렬 테스트하면 호환성 문제를 조기에 발견할 수 있다

비추천:

• ES5 타겟 유지가 필수인 프로젝트: TS 6.0 대신 5.8에 머물러야 한다. 별도 트랜스파일러(Babel/SWC)로 ES5 변환 후 타입 체크만 TS 6.0으로 수행하는 것도 대안이다
• TS 7.0 직행: 시간 여유가 있다면 6.0을 건너뛰고 7.0(Go 컴파일러, 10배 속도)을 기다리는 선택도 유효하다. 단, 7.0에서는 ignoreDeprecations가 제거되므로 사전 준비는 필수다

결론: TypeScript 6.0은 7.0의 Go 컴파일러 전환을 위한 정리 릴리스다. 지금 당장 전환할 필요는 없지만, ignoreDeprecations에 의존하지 않는 깨끗한 코드베이스를 만들어두면 7.0에서 10배 빠른 빌드 속도의 혜택을 바로 누릴 수 있다.