0songha0

타입스크립트 사용하는 리액트 프로젝트 구축 방법

리액트 프로젝트 구축

리액트 프로젝트 생성 명령어

npx create-react-app 프로젝트명

Node.js 설치 후, npx 명령어로 리액트 프로젝트 폴더를 생성할 수 있습니다.
App.test.js, logo.svg, reportWebVitals.js, setupTest.js 파일은 삭제해도 좋습니다.

로고 파일 삭제 시 App.js 수정

import './App.css';

function App() {
  return (
    <div className="App"></div>
  );
}

export default App;

위와 같이, App div 내부 header 요소를 제거해야 합니다.

리액트 프로젝트 타입스크립트 설치

타입스크립트 및 타입 선언 패키지 설치

npm i -D typescript @types/node @types/react @types/react-dom @types/jest

자바스크립트 기반 리액트 프로젝트에 타입스크립트 및 타입 관련 패키지들을 설치합니다.
node_modules 폴더에 @types 폴더가 생성되고, package.json 파일 devDependencies에 패키지들이 추가됩니다.
타입스크립트는 런타임에 실행되지 않으므로 –save-dev 또는 -D 옵션을 통해 개발용 의존성으로 추가합니다.

타입스크립트 옵션 작성

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "strict": true,
    "allowJs": true,
    "esModuleInterop": true,
    "jsx": "react-jsx"
  },
  "include": ["src"]
}

프로젝트 루트 폴더 안에 tsconfig.json 파일 생성 후 필요한 옵션들을 작성합니다.

타입스크립트 옵션 설정
https://0songha0.github.io/web-dev/2025-06-30-1#%ED%83%80%EC%9E%85%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8-%EC%98%B5%EC%85%98-%EC%84%A4%EC%A0%95

기존 js 파일 확장자 변경

타입스크립트는 js 파일에서 DOM을 리턴하거나 렌더링하는 jsx 문법을 해석할 수 없습니다.
기존 js 파일들의 확장자를 jsx 또는 tsx로 변경하면 오류가 해결됩니다.

tsconfig.json 파일 오류 메시지

'/프로젝트경로/프로젝트명/src/App.js' 파일은 입력 파일을 덮어쓰므로 쓸 수 없습니다.

타입스크립트 파일로 마이그레이션

js, jsx 파일들을 tsx 파일로 변경해서 타입 검사를 수행하도록 해야 합니다.
tsx 파일로 변경되면 타입 검사로 인해 문법 오류가 발생하므로 하나씩 해결해나가야 합니다.

tsx 파일 오류 해결

import문 오류 메시지

모듈 '"/프로젝트경로/프로젝트명/node_modules/@types/react-dom/client"'에는 기본 내보내기가 없습니다.

import 대상 js 파일에 default export 문이 없는 경우 발생하는 오류입니다.
기본 내보내기 값이 없는 모듈도 ES6 방식으로 불러오려면 “esModuleInterop”: true 컴파일러 옵션을 추가해야 합니다.

jsx 문법 오류 메시지

'--jsx' 플래그를 제공하지 않으면 JSX를 사용할 수 없습니다.

타입스크립트 컴파일러가 jsx 문법을 해석할 수 있도록, “jsx”: “react-jsx” 컴파일러 옵션을 추가해야 합니다.

index.tsx 오류 메시지

'HTMLElement | null' 형식의 인수는 'Element | DocumentFragment' 형식의 매개 변수에 할당될 수 없습니다.
'null' 형식은 'Element | DocumentFragment' 형식에 할당할 수 없습니다.

(method) Document.getElementById(elementId: string): HTMLElement | null

ReactDom.createRoot 함수는 null 타입 인수를 받지 않아 발생하는 에러입니다.
아래처럼, non null 단언 (!) 또는 단언 (as 타입명) 을 추가하여 해결할 수 있습니다.

const root = ReactDOM.createRoot(document.getElementById("root")!);
또는
const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement);

리액트 타입스크립트 프로젝트 구축

리액트 프로젝트 생성 시 템플릿 옵션으로 타입스크립트를 함께 설치하는 방법도 있습니다.

리액트 타입스크립트 일괄 설치 명령어

npx create-react-app 프로젝트명 --template typescript

타입스크립트 템플릿이 적용된 리액트 프로젝트 설치 명령어입니다.
App.js 등이 App.tsx 등으로 변환되고, 타입 선언 패키지들이 자동 설치됩니다.
타입스크립트 옵션들도 자동으로 설정되어 간편하게 시작할 수 있습니다.

리액트 프로젝트 실행

리액트 실행 명령어

npm run start

package.json 파일 script에 정의된 start 스크립트 명령어로 리액트 개발 서버를 실행합니다.

최신 글