기존 Vite + React 프로젝트에 TypeScript 추가하기 (마이그레이션 정리)

 

 

📚

사이드 프로젝트를 새로 시작했다.

기존에 세팅은 되었던 프로젝트라, Vite + React(JavaScript) 프로젝트에 TypeScript를 추가하면서 겪었던 과정과 필요한 설정을 정리해보았다.

---

1. TypeScript 설치

먼저 프로젝트에 TypeScript와 React 타입을 설치한다.

npm install -D typescript @types/react @types/react-dom

설치가 완료되면 TypeScript 설정 파일을 생성한다.

npx tsc --init

그러면 프로젝트 루트에 tsconfig.json 파일이 생성된다.

 

2. tsconfig.json 설정

기본 생성된 tsconfig.json을 Vite 환경에 맞게 일부 수정했다.

{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],

    "module": "ESNext",
    "moduleResolution": "Bundler",

    "jsx": "react-jsx",

    "strict": true,
    "skipLibCheck": true,

    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,

    "allowJs": true
  },
  "include": ["src"]
}

 

✅주요 옵션

- strict

 TypeScript의 타입 검사를 엄격하게 한다.

 

- allowJs

 기존 JavaScript 파일을 그대로 사용할 수 있게 해준다.
 기존 프로젝트에 TypeScript를 도입할 때 유용함. 파일이 많을 때는 중요!

 

- moduleResolution: Bundler

Vite 환경에 맞는 모듈 해석 방식

 

3. vite-env.d.ts 생성

Vite 프로젝트에서는 환경 변수 타입을 위해
vite-env.d.ts 파일이 필요하다.

src 폴더 안에 아래 파일을 생성하고 내용은 다음과 같다.

/// <reference types="vite/client" />

이 파일이 있어야 import.meta.env.VITE_API_URL 같은 코드에서 타입이 정상적으로 작동한다.

 

4. vite.config.js → vite.config.ts 변경

Vite 설정 파일도 TypeScript로 변경할 수 있다.

vite.config.js → vite.config.ts

 

 

5. main 파일 먼저 TypeScript로 변환

기존 프로젝트를 TypeScript로 마이그레이션할 때는 entry 파일부터 변환하는 것이 좋다고 한다.

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

 

여기서 !는 Non-null assertion으로
root 요소가 null이 아니라는 것을 TypeScript에게 알려주는 역할을 한다.

 

main 이후로는 App 컴포넌트, 다른 컴포넌트들을 하나씩 변환해주면 된다.

기존 프로젝트를 TypeScript로 마이그레이션할 때는 보통 이러한 순서로 진행하는 것이 좋다고.. (아무래도)

 

---

💡 타입 정의

1. Props 타입 정의

컴포넌트를 TypeScript로 변환할 때는 Props 타입을 정의해준다.

type ButtonProps = {
  children: React.ReactNode;
  onClick?: () => void;
};

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

이렇게 하면 컴포넌트를 사용할 때 타입 체크가 가능해진다.

2. API 타입 정의

API 데이터를 사용할 때도 타입을 정의해준다.

interface User {
  id: number;
  name: string;
}

axios 요청에서도 타입을 지정할 수 있다.

axios.get<User[]>("/api/users");

 

실무에서는 위처럼 정의한 타입을 별도 폴더로 관리하는 경우가 많다.

src
 ├ components
 ├ hooks
 ├ api
 ├ types
 ├ utils
 └ pages

 

src/types/user.ts

export interface User {
  id: number;
  name: string;
}

 

---

 

마무리

기존 Vite + React 프로젝트에 TypeScript를 적용할 때 필요한 과정

1. TypeScript 설치
2. tsconfig.json 생성 및 설정
3. vite-env.d.ts 생성
4. vite.config.ts 변환
5. main.tsx부터 변환
6. 컴포넌트를 하나씩 TypeScript로 변환
7. Props와 API 타입 정의

처음에는 번거롭게 느껴질 수 있지만
프로젝트 규모가 커질수록 TypeScript의 장점이 크게 느껴진다.

앞으로는 새 프로젝트를 만들 때
처음부터 React + TypeScript로 시작하는 것이 더 좋은 선택일 것 같다.