자바스크립트(JavaScript)로만 프로젝트를 진행하다가 안정성을 높이기 위해 타입스크립트(TypeScript)를 처음 도입했을 때, 기쁨보다 당혹감이 훨씬 컸습니다.
분명 자바스크립트에서는 아무 문제 없이 잘 돌아가던 코드인데, 타입스크립트를 적용하자마자 VS Code 에디터 온 동네에 빨간 줄(Type Error)이 그어지며 화면이 온통 경고 메시지로 뒤덮였기 때문입니다.
당시에는 "개발 속도만 늦어지는 것 같은데 왜 쓸까?" 싶었지만, 타입 에러를 하나씩 해결해 나가면서 런타임(실행 시점)에서 터질 위험한 버그를 코드 작성 단계에서 미리 잡아주는 강력함을 체감하게 되었습니다.
오늘은 제가 타입스크립트 초보 시절 가장 자주 마주치며 식은땀을 흘렸던 대표적인 타입 에러 3가지와 완벽한 해결법을 정리해 보려고 합니다.
1. 에러 1: Object is possibly 'null' or 'undefined'
API 데이터를 받아오거나 DOM 요소를 참조할 때 가장 흔하게 만나는 에러입니다.
// ❌ 빨간 줄이 뜨는 과거의 코드
const nameLength = response.user.name.length;
// 🚨 Error: 'response.user' is possibly 'undefined'.
💡 원인 및 해결책
타입스크립트는 response.user 데이터가 서버 응답 지연이나 에러로 인해 undefined 상태일 가능성을 미리 경고해 주는 것입니다. 만약 이 상태로 자바스크립트에서 실행되었다면 런타임에 그 악명 높은 Cannot read properties of undefined 에러가 터졌을 것입니다.
해결을 위해 옵셔널 체이닝(?.)이나 타입 가드(Type Guard)를 활용하면 깔끔하게 해결됩니다.
// ⭕ 옵셔널 체이닝으로 안전하게 접근
const nameLength = response.user?.name?.length;
// ⭕ 또는 타입 가드(if문)로 안전성 보장
if (response.user && response.user.name) {
const nameLength = response.user.name.length;
}
2. 에러 2: Property 'X' does not exist on type 'Y' (이벤트 객체 / 객체 키 접근 에러)
리액트에서 onChange 이벤트를 처리하거나, 객체의 키(Key)로 동적 접근을 시도할 때 자주 발생하는 에러입니다.
// ❌ e.target.value에서 빨간 줄이 뜨는 코드
const handleChange = (e) => {
console.log(e.target.value);
// 🚨 Error: Parameter 'e' implicitly has an 'any' type.
};
💡 원인 및 해결책
타입스크립트는 매개변수 e가 어떤 이벤트 객체인지 알지 못하므로 암묵적인 any 타입 경고를 보냅니다. 리액트에서 제공하는 이벤트 타입(React.ChangeEvent 등)을 명시해 주어야 합니다.
// ⭕ React의 HTMLInputElement 타입을 정확히 명시
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
console.log(e.target.value); // 이제 에러 없이 자동완성까지 지원됨!
};
3. 에러 3: Type 'X' is not assignable to type 'Y' (상태 초기값 타입 불일치)
useState를 사용할 때 초기값 타입과 나중에 넣어줄 API 데이터의 타입이 달라서 발생하는 에러입니다.
// ❌ null로 초기화해 두었더니 나중에 객체를 넣을 때 에러 발생
interface UserProfile {
id: number;
name: string;
}
const [user, setUser] = useState(null);
// 나중에 API 응답 후 setUser 호출 시 에러!
setUser({ id: 1, name: '김개발' });
// 🚨 Error: Argument of type '{ id: number; name: string; }' is not assignable to parameter of type 'null'.
💡 원인 및 해결책
useState(null)로 작성하면 타입스크립트는 user 변수의 타입을 오직 null로만 추론해 버립니다. 제네릭(<T>)을 사용해 "초기엔 null이지만 나중에 UserProfile 객체가 들어올 수 있다"라고 명시해 주어야 합니다.
// ⭕ 제네릭과 유니온 타입을 활용해 두 가지 가능성을 모두 열어둠
const [user, setUser] = useState<UserProfile | null>(null);
// 이제 객체를 넣어도 빨간 줄 없이 정상 동작!
setUser({ id: 1, name: '김개발' });
4. 회고 및 느낀 점
타입스크립트를 처음 시작했을 때는 일일이 타입을 적어주는 행위가 개발 속도를 갉아먹는 걸림돌처럼 느껴졌습니다.
하지만 수많은 빨간 줄과 싸우고 해결해 나가는 과정에서 "내가 작성하는 코드의 데이터 흐름을 훨씬 객관적이고 안전하게 파악하는 습관"을 가질 수 있게 되었습니다.
지금 타입스크립트의 빨간 줄 때문에 스트레스를 받고 계신 초보 개발자분들이 계시다면, 에러 메시지를 무서워하지 마시고 "타입스크립트가 미래의 런타임 에러를 대신 막아주고 있구나!" 하고 긍정적으로 바라보시면 될 것 같습니다!
'개발일기' 카테고리의 다른 글
| [JS] for문만 돌리던 내가 map, filter, reduce를 자유자재로 쓰게 된 계기 (0) | 2026.08.05 |
|---|---|
| [성능최적화] PNG 용량 2.4MB의 공포: WebP와 AVIF로 웹사이트 로딩 속도 90% 줄여본 후기 (0) | 2026.08.03 |
| [Next.js] 메인 페이지 로딩 속도가 3초? Next.js Image 컴포넌트로 0.8초까지 줄여본 삽질기 (0) | 2026.07.29 |
| [Git] "내 코드가 어디 갔지?" 초보 개발자가 자주 범하는 Git 실수 3가지와 해결법 (0) | 2026.07.28 |
| [CSS] Tailwind CSS 도입 후기: BEM 클래스명 지옥 탈출과 가독성 극복 전략 (0) | 2026.07.28 |
