React 프로젝트에 TypeScript 도입하기 – 실전 마이그레이션 가이드

React 프로젝트에 TypeScript 도입하기 – 실전 마이그레이션 가이드

---

React 프로젝트를 운영하다 보면
컴포넌트 간 props 전달 오류, state 타입 혼동, API 응답 구조 불일치 등
수많은 버그가 사소한 코드 실수에서 발생합니다.

이런 문제를 근본적으로 해결해주는 도구가 바로 TypeScript입니다.
이번 글에서는 React 프로젝트에 TypeScript를 도입하는 실전 방법을 정리하고,
컴포넌트, props, state, API 응답 구조에 타입을 지정하는 법까지 안내합니다.

---

✅ 1. 기존 프로젝트에 TypeScript 추가하기

npm install --save-dev typescript @types/react @types/react-dom

🔄 주요 변경

• src/index.js → src/index.tsx
• 컴포넌트 파일 확장자: .jsx → .tsx
• 타입 정보 없는 패키지는 @types/패키지명 설치 필요

mv App.js App.tsx
mv index.js index.tsx

---

🧠 2. props에 타입 지정하는 법

type ButtonProps = {
  label: string;
  onClick: () => void;
};

function Button({ label, onClick }: ButtonProps) {
  return <button onClick={onClick}>{label}</button>;
}

✅ props는 항상 type 또는 interface로 명확하게 정의
✅ onClick, onChange, children 등 모두 타입 지정 가능

---

🔄 3. useState의 타입 지정법

반응형

const [count, setCount] = useState<number>(0);
const [user, setUser] = useState<{ name: string; age: number } | null>(null);

✅ 초기값이 null일 수 있다면 | null 추가 필수
✅ 배열, 객체 등 복잡한 타입도 선언 가능

---

📡 4. API 응답 타입 정의

type User = {
  id: number;
  name: string;
  email: string;
};

const [users, setUsers] = useState<user[]>([]);

useEffect(() => {
  axios.get<user[]>("https://api.example.com/users")
    .then((res) => setUsers(res.data));
}, []);
</user[]></user[]>

✅ axios.get<User[]>()으로 응답 타입 지정
✅ API의 구조를 정확히 반영할 수 있어 오류 예방

---

🧱 5. 공통 타입 분리 구조 추천

/src
  /types
    user.ts
    product.ts

// user.ts
export type User = {
  id: number;
  name: string;
  email: string;
};

import { User } from "../types/user";

✅ 공통 타입을 모듈화해서 관리하면 협업, 유지보수, 재사용성 상승

---

💡 6. React.FC 타입은 어떻게?

const MyComponent: React.FC<{ name: string }> = ({ name }) => {
  return <h1>{name}</h1>;
};

✅ React.FC는 children 포함 자동 타입
⚠️ 하지만 최근에는 명시적으로 타입 선언하는 방식이 더 선호됨 (불필요한 타입 강제 때문)

---

📦 실전 예제 – ProductCard 컴포넌트

type Product = {
  id: number;
  name: string;
  price: number;
};

type ProductCardProps = {
  product: Product;
};

function ProductCard({ product }: ProductCardProps) {
  return (
    <div>
      <h2>{product.name}</h2>
      <p>{product.price.toLocaleString()}원</p>
    </div>
  );
}

---

🧠 오늘의 요약

항목 설명

파일 확장자	.tsx로 변경
props 타입	type 또는 interface 사용
useState 타입	<number>, <string[]>, `<T
API 응답	axios.get<T>()로 응답 타입 정의
공통 타입 분리	src/types 디렉토리로 관리

---

🧪 실습 과제

1. 기존 컴포넌트 파일들을 .tsx로 변경해보세요
2. Button, Card, Input 등 컴포넌트에 props 타입을 지정해보세요
3. 공통 타입 폴더를 만들고 API 응답 구조를 정의해보세요

---

📌 다음 글 예고

👉 React Hook 사용 전략 – 커스텀 훅으로 비즈니스 로직 정리하기

• 반복되는 useEffect, API 로직 추출
• useUser, useToggle, useFetch 훅 패턴 만들기
• 실무에서 유용한 커스텀 훅 설계 팁

 

React TypeScript, React tsx, props 타입 정의, useState 타입 지정, TypeScript API 응답, 타입 분리 구조, React 타입 가이드, React 프로젝트 마이그레이션, TypeScript 실전 예제, 타입 안정성 향상