언어난이도 보통⏱ 점진적(파일 단위, 수일~수주)
JavaScript에서 TypeScript로 점진 마이그레이션
JavaScript→TypeScript
요약: allowJs로 JS·TS를 공존시키고 파일을 하나씩 .ts/.tsx로 바꾸며 타입을 입히는 점진 전략이 안전합니다. strict는 마지막에 켭니다.
왜 옮기나
- 타입으로 런타임 에러(undefined 접근·타입 불일치)를 컴파일 단계에서 잡습니다.
- 에디터 자동완성·리팩터링 안전성이 크게 좋아집니다.
- 협업 시 함수 시그니처가 문서 역할을 합니다.
전제 — 현재 상태
순수 JavaScript 프로젝트, .js/.jsx 파일, 타입 없음.
마이그레이션 단계
1
TypeScript 설치와 tsconfig 생성
TypeScript와 노드/리액트 타입을 설치하고 tsconfig를 만듭니다.
npm install -D typescript @types/node @types/react @types/react-dom
npx tsc --init2
allowJs로 공존 허용
tsconfig에서 allowJs를 켜면 기존 .js를 그대로 둔 채 점진 전환할 수 있습니다. 처음엔 strict를 꺼두는 것이 부담이 적습니다.
// tsconfig.json
{ "compilerOptions": { "allowJs": true, "strict": false, "jsx": "preserve" } }3
리프 모듈부터 .ts로 전환
의존성이 적은 유틸·상수 파일부터 .ts로 바꾸고 타입을 입힙니다. 외부 의존이 많은 진입점은 마지막에.
4
타입 없는 패키지 처리
@types가 없는 패키지는 설치하거나, 임시로 모듈 선언으로 막습니다.
// global.d.ts
declare module 'untyped-pkg'5
strict 단계적 강화
전환이 끝나면 strict, noImplicitAny, strictNullChecks를 차례로 켜며 남은 any와 null 위험을 정리합니다.
⚠️ 막히는 케이스 · 함정
- any를 남발하면 타입의 이점이 사라집니다 — unknown + 타입 가드를 우선.
- JSX가 있는 파일은 .tsx여야 합니다(.ts는 JSX 파싱 안 됨).
- strict를 처음부터 켜면 에러가 폭발하니 전환 후 단계적으로.
✅ 검증: npx tsc --noEmit로 타입 에러 0을 확인하고, 빌드와 테스트가 통과하는지 점검합니다.
TypeScriptJavaScripttsconfigallowJsstrict