[TypeScript] React TypeScript 프로젝트 생성과 초기 세팅

들어가며

React를 TypeScript와 함께 사용하면 props, state, API 응답 타입을 더 안전하게 다룰 수 있습니다.

처음에는 설정 파일이 많아 보여서 어렵게 느껴질 수 있지만, 프로젝트 생성 흐름만 알면 크게 복잡하지 않습니다.

이번 글에서는 React TypeScript 프로젝트를 생성하고, 초기에 확인하면 좋은 파일들을 정리해볼게요.

---

프로젝트 생성하기

Create React App을 기준으로 TypeScript 템플릿을 사용하면 다음 명령어로 프로젝트를 만들 수 있습니다.

npx create-react-app my-app --template typescript

명령어가 끝나면 my-app 폴더가 생성됩니다.

cd my-app
npm start

위 명령어로 개발 서버를 실행하면 기본 React 화면을 확인할 수 있습니다.

---

생성되는 주요 파일

TypeScript 템플릿으로 생성하면 일반 React 프로젝트와 다르게 .tsx, .ts 파일이 함께 만들어집니다.

src
├─ App.tsx
├─ index.tsx
├─ react-app-env.d.ts
└─ ...

App.tsx는 JSX를 사용하는 TypeScript 컴포넌트 파일입니다.

index.tsx는 React 앱의 진입점입니다.

react-app-env.d.ts는 Create React App에서 필요한 타입 선언을 연결하는 파일입니다.

---

tsconfig.json 확인하기

tsconfig.json은 TypeScript 컴파일 옵션을 관리하는 파일입니다.

CRA TypeScript 템플릿에서는 보통 자동으로 생성됩니다.

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  },
  "include": ["src"]
}

처음에는 모든 옵션을 외우기보다 strict, jsx, include 정도를 먼저 보면 좋습니다.

strict는 타입 검사를 더 엄격하게 하는 옵션입니다.

jsx는 JSX를 어떻게 변환할지 정합니다.

include는 TypeScript가 검사할 파일 범위를 지정합니다.

---

이미지 import 타입 에러가 날 때

이미지 파일을 import할 때 타입 에러가 발생하는 경우가 있습니다.

import logo from "./logo.png";

이럴 때는 타입 선언 파일을 추가할 수 있습니다.

declare module "*.svg";
declare module "*.png";
declare module "*.jpg";
declare module "*.jpeg";

보통 src/react-app-env.d.ts 또는 별도의 src/types/assets.d.ts 파일에 작성합니다.

이 선언은 TypeScript에게 이미지 파일 import를 허용한다고 알려주는 역할을 합니다.

---

불필요한 파일 정리하기

처음 생성된 프로젝트에는 학습용 파일이 함께 들어 있습니다.

프로젝트 성격에 따라 아래 파일은 지워도 됩니다.

• App.test.tsx
• logo.svg
• reportWebVitals.ts
• setupTests.ts

파일을 삭제했다면 import하고 있는 코드도 함께 정리해야 합니다.

예를 들어 index.tsx에서 reportWebVitals를 사용하고 있다면 해당 import와 호출도 제거합니다.

---

마무리

React TypeScript 프로젝트는 생성 명령어 자체는 간단하지만, 초기에 어떤 파일이 어떤 역할을 하는지 이해하는 것이 중요합니다.

tsx 파일은 React 컴포넌트, tsconfig.json은 TypeScript 설정, d.ts 파일은 별도 타입 선언을 담당합니다.

처음에는 기본 템플릿을 그대로 실행해보고, 그다음 불필요한 파일을 정리하면서 구조를 익히면 훨씬 편하게 시작할 수 있습니다.