타입스크립트 프로젝트 품질을 높이는 실무 40개 점검 항목 모음. strict 모드와 noImplicitAny 단계적 적용법, tsconfig 필수 옵션, ESLint typescript-eslint 타입 기반 규칙, any 제거 패턴, Vitest 타입 커버리지, CI 파이프라인 tsc --noEmit 통합까지. 1인 개발 사이드 프로젝트부터 팀 프로젝트까지 적용 가능한 타입스크립트 코드 품질 관리 체크리스트.
타입스크립트(TypeScript) 프로젝트를 시작하면서 strict: false로 두면 "나중에 고치면 되겠지"라고 생각한다. 6개월 뒤 그 부채가 쌓여 타입 에러 수백 개와 마주하는 건 제가 직접 겪은 일이다. 잘 짜인 타입스크립트 설정과 품질 체계는 코드 작성 초기에 잡아야 한다. 나중에 고치는 비용은 처음의 5배다.
이 글은 타입스크립트 프로젝트를 운영하면서 검증한 40개 항목의 품질 체크리스트다. tsconfig 설정, strict 모드, 린터(ESLint) 규칙, 타입 패턴, CI/CD 파이프라인까지 순서대로 점검한다. 팀 규모와 관계없이 적용 가능하며, 항목마다 실무 근거와 설정 예시를 함께 적었다.
strict: true는 타입스크립트 공식 문서에서 "신규 프로젝트에서는 활성화를 강력 권장"한다고 명시한 설정이다. 이 옵션 하나가 8가지 세부 규칙을 한 번에 켠다. strictNullChecks, noImplicitAny, strictFunctionTypes 등이 포함된다.
기존 프로젝트에 strict: true를 한 번에 켜면 수백 개의 에러가 터진다. 이 경우에는 strictNullChecks → noImplicitAny 순으로 하나씩 켜며 단계적으로 적용하는 게 현실적이다. 각 단계를 별도 PR로 나눠 처리하면 코드 리뷰 부담도 줄어든다.
strict 외에도 프로젝트 성격에 따라 설정해야 할 옵션이 있다. Next.js, Node.js, 라이브러리 — 용도별로 최적 값이 다르다. 잘못된 moduleResolution 설정 때문에 패키지 임포트가 깨지거나, 잘못된 target 때문에 빌드 결과물이 구형 브라우저에서 동작하지 않는 사고는 흔하다.
2026년 기준 Node.js 22+ 환경에서는 "module": "NodeNext"와 "moduleResolution": "NodeNext"를 사용하는 게 표준이 됐다. 브라우저 번들러 기반(Next.js, Vite)이라면 "bundler"를 선택한다. module과 moduleResolution이 쌍이 맞지 않으면 예상치 못한 임포트 오류가 발생한다.
@typescript-eslint/eslint-plugin은 타입스크립트 전용 린트 규칙 집합이다. 기본 ESLint만 쓰면 타입 기반 검사(예: no-floating-promises)가 동작하지 않는다. 타입스크립트 프로젝트에서는 타입 정보를 활용하는 규칙이 핵심이다.
2026년부터 @typescript-eslint/eslint-plugin v8이 안정화됐으며, flat config 방식으로 전환이 권장된다. 기존 .eslintrc 방식은 폐기 예정이므로 신규 프로젝트는 eslint.config.mjs를 사용한다. 프리티어(Prettier) 또는 바이옴(Biome)과 포맷 규칙 충돌도 반드시 확인해야 한다.
코드베이스에서 any를 완전히 없애는 것은 현실적으로 어렵다. 외부 라이브러리 타입이 부정확하거나, JSON 응답 구조가 유동적일 때 any가 유혹한다. 하지만 any 대신 unknown을 쓰고 타입 가드를 적용하면 런타임 에러를 컴파일 타임에 잡을 수 있다.
API 응답 타입은 Zod, Valibot 같은 런타임 검증 라이브러리로 이중으로 보호하는 게 2026년 표준이다. 타입스크립트는 컴파일 타임만 검사하고 런타임은 보장하지 않는다는 점을 잊어선 안 된다. 타입 선언이 올바르더라도 실제 서버 응답이 다른 형태로 오면 런타임에서 터진다.
타입스크립트 프로젝트에서 테스트는 두 레이어다. 타입 시스템이 컴파일 타임에 검사하고, 테스트 코드가 런타임 로직을 검사한다. 두 레이어가 겹치는 부분도 있지만, 각자 역할이 다르다. 타입 에러가 없다고 버그가 없다는 뜻이 아니다.
Vitest는 2026년 기준 타입스크립트 프로젝트에서 가장 많이 쓰이는 테스트 프레임워크다. Jest보다 설정이 단순하고 타입스크립트 네이티브 지원이 강력하다. vitest --typecheck 옵션으로 타입 검사와 테스트를 함께 실행할 수 있어 CI 파이프라인 구성이 단순해진다.
로컬에서는 잘 동작하던 코드가 CI에서 타입 에러로 빌드가 실패하는 상황은 팀 전체 흐름을 막는다. 반대로 CI에 타입 검사를 빠뜨리면 any가 몰래 유입되고 품질이 서서히 낮아진다. 이 두 극단을 피하려면 CI 파이프라인을 명확하게 구성해야 한다.
타입 검사(tsc --noEmit)는 린트 다음, 빌드 이전에 위치시키는 게 일반적이다. 실제 빌드는 tsc가 아니라 번들러(Vite, Webpack, esbuild)가 담당하므로 타입 검사와 빌드는 분리해서 실행한다. 번들러는 타입 에러가 있어도 빌드를 성공시키기 때문이다.
타입스크립트 컴파일 속도는 프로젝트 규모에 비례해 느려진다. 코드 10만 줄 이상이면 tsc 단독 실행이 1분을 넘기도 한다. 이 문제를 해결하는 주요 방법은 증분 빌드(incremental: true)와 프로젝트 레퍼런스 활용이다.
esbuild나 SWC는 타입 검사를 건너뛰고 트랜스파일만 하기 때문에 매우 빠르다. 이 때문에 번들러가 타입스크립트를 처리하더라도 tsc --noEmit 타입 검사는 반드시 별도로 실행해야 한다. import type 구문을 활용하면 타입 전용 임포트가 번들에서 완전히 제거돼 최종 번들 크기도 줄어든다.
혼자 프로젝트를 시작하면 일관성을 유지하기 쉽다. 팀이 늘어나면 각자 다른 스타일로 타입을 작성하기 시작한다. 어떤 사람은 interface를, 어떤 사람은 type을 쓴다. 선택이 중요한 게 아니라 일관성이 중요하다. ESLint 규칙과 함께 팀 규약을 문서화해 놓으면 리뷰 시간을 줄일 수 있다.
@typescript-eslint/consistent-type-definitions 규칙을 interface 또는 type 중 하나로 고정하면 코드 리뷰 시 불필요한 논쟁이 사라진다. 기술적 선택보다 팀 합의가 더 중요하며, 린터로 강제하면 사람이 직접 지적하지 않아도 된다.
--typecheck 옵션 설정법권장하지 않는다. 기존 코드베이스가 크면 수백 개의 에러가 한 번에 터진다. strictNullChecks를 먼저 켜고, 에러를 수정한 뒤 noImplicitAny를 켜는 식으로 단계적으로 적용한다. 각 단계를 별도 PR로 나눠 처리하면 리뷰 부담도 줄어든다. 일주일에 옵션 하나씩 켜는 방식이 무리 없이 전환하는 현실적인 방법이다.
기술적으로는 둘 다 대부분의 상황에서 동일하게 동작한다. 타입스크립트 공식 팀은 객체 모양 정의에 interface를, 유니온·인터섹션 같은 복잡한 타입 연산에 type을 권장한다. 가장 중요한 건 팀 내 일관성이다. 하나를 골라 린터로 강제하면 코드 리뷰 때 논쟁이 사라진다.
생략하면 안 된다. esbuild나 SWC 기반 번들러는 타입 검사를 건너뛰기 때문에 타입 에러가 있어도 빌드가 성공한다. tsc --noEmit은 타입 에러를 잡는 유일한 정식 방법이다. 느린 문제는 incremental: true와 캐시 활용으로 해결한다. CI 캐시를 tsconfig.tsbuildinfo 파일 기준으로 설정하면 변경된 파일만 재검사해 속도가 크게 개선된다.
외부 라이브러리 타입이 부정확하거나 마이그레이션 중인 경우 일부 any가 불가피하다. 현실적인 목표는 "코드베이스 전체 10개 이하"로 제한하고, 각 any에 // TODO: 타입 강화 필요 주석을 달아 추적하는 것이다. 무조건 0개를 목표로 하면 개발 속도만 떨어진다. 중요한 건 any가 모르는 새 유입되지 않도록 린터로 경고를 켜두는 것이다.
마이너 버전(예: 5.4 → 5.5)은 6개월 이내 적용을 목표로 한다. 타입스크립트는 마이너 버전에도 새 린터 규칙이나 타입 추론 개선이 포함되며, 너무 뒤처지면 최신 린터 플러그인과 호환성 문제가 생긴다. 메이저 버전(5.x → 6.x)은 별도 마이그레이션 가이드를 참고해 계획적으로 진행한다. 의존성 관리 도구(Renovate, Dependabot)를 설정해 두면 버전 업그레이드 PR이 자동으로 올라와 놓치지 않는다.
모든 항목을 다 적용할 필요는 없다. 1인 사이드 프로젝트라면 최소한 strict: true, 린터(ESLint + @typescript-eslint), CI 타입 검사(tsc --noEmit) 세 가지만 적용해도 된다. 코드베이스가 커질수록 나머지 항목을 하나씩 추가하면 자연스럽다. 처음부터 40개를 모두 셋업하려다 시작 자체가 늦어지는 것보다 핵심 3개로 시작하는 게 낫다.
