기존 자바스크립트 프로젝트에 타입스크립트를 점진 도입하며 잡은 치명적 버그들

핵심 결론

kimura512.dev는 순수 자바스크립트로 개발을 시작한 후 점진적으로 엄격한 타입스크립트로 체계를 고도화했습니다. 나중에 도입하는 정적 타입의 진정한 가치는 새로운 기능 추가가 아니라 '런타임까지 숨어 있던 불안정한 가정을 조기에 적발하는 것'에 있습니다. 타입 에러가 완전히 해소될 때까지 운영 배포를 멈추고 버그 수정과 기능 추가 커밋을 철저히 분리했습니다.

1. 다국어 번역 키 누락 사전 적발

다국어 번역 데이터를 관리할 때 특정 언어 번역이 누락되어도 런타임에는 에러 없이 빈 문자열로 표시되어 방치되기 쉽습니다. 타입을 Record<Language, string>으로 정밀하게 제한함으로써 누락된 번역이 존재할 경우 빌드 단계에서 즉시 실패하도록 강제했습니다.

2. 마크다운 링크 파싱의 방어 로직 강화

게시글 내 링크 파싱 시 링크 주소가 항상 존재할 것이라는 암묵적 가정이 있었습니다. 문법 트리에서 href 속성이 옵셔널인 상황을 고려하지 않은 코드는 잠재적 장애 요인이었습니다. 명시적 타입을 부여하면서 비어 있는 링크에 대한 방어 코드를 안전하게 정비했습니다.

3. 일관된 ISO 날짜 데이터 보장

과거 작성된 일부 글의 날짜 표기 형식이 미세하게 달라 특정 브라우저 환경에서 Invalid Date로 렌더링되던 이슈를 발견했습니다. 인터페이스에 날짜 포맷 규격을 강제하여 빌드 시점에 오류 데이터를 바로잡았습니다.

4. 불안전한 'as' 단언문 제거

외부 API 응답을 무조건 as로 캐스팅하던 기존 패턴을 걷어내고, 네트워크 경계에서 런타임 검증을 거치도록 재설계하여 비정상 데이터가 내부 시스템으로 유입되는 경로를 원천 차단했습니다.

5. 최신 프레임워크 렌더링 타입 일원화

컴포넌트 리팩토링 과정에서 useRef 기본값 누락 및 ReactNode 자식 요소 처리의 모호함을 정리하여 안정적인 렌더링을 보장했습니다.

6. 프로덕션 빌드를 최종 방파제로 활용

로컬 개발 환경에서는 정상 작동하더라도 배포 파이프라인의 엄격한 빌드 단계에서 잠재적 결함이 감지됩니다. 단위 테스트가 가벼운 개인 프로젝트에서 엄격한 빌드 프로세스는 가장 확실한 품질 안전장치입니다.

7. 컴포넌트 Props 유니온 타입 설계

핵심 UI 카드 컴포넌트의 variant 속성을 유니온 타입으로 한정하여 오타나 지원 중단된 스타일 속성이 주입되는 문제를 컴파일 레벨에서 차단했습니다.

8. 리팩토링 커밋의 순수성 유지

타입 결함을 수정한 변경 사항은 신규 기능 개발과 절대 섞지 않고 독립된 커밋으로 기록하여 유지보수성을 극대화했습니다.

요약

데이터가 유입되는 첫 관문부터 타입을 견고하게 잠그면, UI 계층의 불필요한 수정 없이도 애플리케이션 전체의 안정성이 급격히 향상됩니다.

운영 메모

Q. strict 모드를 처음부터 한 번에 적용했는가?
규칙을 한 번에 모두 켜지 않고 주 단위로 규칙을 순차 활성화하며 안정적으로 마이그레이션했습니다.

Q. any 타입은 완전히 제거되었는가?
외부 서드파티 라이브러리 연동 경계를 제외한 모든 내부 코드에서 완전히 퇴출했습니다.