[React] React + Vite + TypeScript 프로젝트 생성하기

자주 사용하는 프로젝트 셋팅을 공유하고 각 정의와 역할, 그리고 사용하는 의미에 대해 정리해보고자 한다!

Vite는 무엇인가?

Vite는 프랑스어로 "빠르다(Quick)"라는 뜻을 가진 단어로, 프론트엔드 개발 도구이다.

이름처험 빌드와 개발 서버 구동 시간이 빠르다는 장점이 있다.

내부적으로 사용하는 ESBuild는 Go라는 네이티브 언어로 만들어진 도구를 이용해 빌드하기 때문에 속도가 빠르다고 한다!

기존 webpack과 같은 모듈 번들러를 이용할 때는 애플리케이션 내 모든 소스 코드에 대해 크롤링 및 빌드 작업을 마쳐야지만이 실제 페이지를 제공할 수 있었다. 즉 프로젝트에 있는 모든 JavaScript, CSS, 이미지 파일 등을 한 번에 묶어서(번들링) 개발 서버에 올렸다. 개발 서버를 실행할 때 전체 빌드 -> 서버 실행 순서로 진행되기 때문에 시간이 오래 걸린다는 한계가 있었다.

Vite는 Native ESM(ECMAScript Modules)와 네이티브 언어 기반 도구를 활용하여 접근한다.

최신 브라우저는 이미 ESM(모듈 시스템)을 기본적으로 지원한다. 이는 번들러가 아닌 ESM을 이용해 어떤 모듈이 수정되면 vite는 그저 수정된 모듈과 관련된 부분만을 교체할 뿐이고, 브라우저에서 해당 모듈을 요청하면 교체된 모듈을 전달한다. "필요할 때만 가져오기(on-demand)" 구조이기 때문에 초기 실행이 매우 빠르다.

또한 Vite는 내부적으로 ESBuild라는 도구를 쓴다고 한다. ESBuild는 Go 언어(네이티브 언어)로 작성되었기 때문에 자바스크립트로 만든 번들러보다 훨씬 빠르게 동작한다는 장점이 있다.

다음으로 Vite를 이용해 프로젝트를 생성해보자!

프로젝트 생성하기

Step1 | Vite 기반 리액트 프로젝트 생성하기

@latest는 npm 패키지를 설치할 때 항상 최신 버전을 가져오도록 하는 태그이다.

이후 Project name과 Package name을 지정한다.

#yarn
yarn create vite

#npm
npm create vite@latest

#pnpm
pnpm create vite

Step2 | framework 설정하기

React, TypeScript+SWC로 선택해준다.

Step3 | 프로젝트 실행하기

이후 해당 명령어를 통해 프로젝트를 실행할 수 있다!

cd WEB_9th
yarn
yarn dev

다음과 같은 화면을 확인했다면 Vite 프로젝트를 성공적으로 생성한 것이다 :)

필수 폴더 및 파일

처음 프로젝트를 설정할 때 헷갈렸던 세팅 방법이나 옵션도 함께 정리해보았다.

my-web/
├─ node_modules/        # 설치된 라이브러리 (자동 생성, 수정 X)
├─ public/              # 정적 파일 (이미지, favicon 등)
├─ src/                 # React 핵심 코드
│  ├─ App.tsx           # 최상위 컴포넌트
│  ├─ main.tsx          # 진입점: App을 root DOM에 마운트
├─ index.html           # 루트 HTML (React가 붙는 곳)
├─ tsconfig.json        # TypeScript 설정
├─ vite.config.ts       # Vite 빌드/개발 서버 설정
├─ package.json         # 프로젝트 의존성 및 스크립트 관리

각 파일 및 폴더 설명

파일	설명
src/	React 프로젝트의 핵심 코드(컴포넌트, 로직, 스타일)가 들어간다.
src / main.jsx	React앱의 진입점 <App />를 DOM에 마운트하는 역할을 한다.
src / index.css	전제에 적용되는 전역 스타일 파일(없애도 되지만 유용)
index.html	React 앱이 마운트되는 HTML 파일 <div id="root"></div>가 포함되어 있으며, 실제 브라우저에 최초 로딩되는 페이지
vite.config.js	Vite의 설정 파일 (빌드 옵션, 플러그인, 경로 별칭 등)
.gitignore	Git에 올리지 않을 파일 및 폴더를 정의한다.
README.md	프로젝트 설명 문서 (설치 방법, 실행 방법 등 기록)
package.json	프로젝트 의존성, 스크립트 관리
tsconfig.json	TypeScript 기본 설정 파일 (컴파일 옵션 정의)
tsconfig.node.json	Node 환경(빌드, 설정 스크립트 등)을 위한 TypeScript 설정
tsconfig.app.json	앱 코드(src/)를 위한 TypeScript 설정
yarn.lock	설치된 패키지 버전을 고정해 프로젝트 환경을 동일하게 유지

권장 유지 구조

프로젝트를 생성할 때 보통 다음과 같은 구조를 권장한다.

my-web/
├─ node_modules/          # 설치된 라이브러리 (자동 생성, 수정 X)
├─ public/                # 정적 파일 (favicon, 로고, 이미지 등)
├─ src/                   # ⚡️ 핵심 앱 코드
│  ├─ App.tsx             # 최상위 컴포넌트
│  ├─ main.tsx            # 진입점: App을 DOM에 마운트
│  ├─ index.css           # 전체 전역 스타일 (선택적이지만 권장)
│  └─ components/         # 재사용 컴포넌트 모음 (권장)
├─ index.html             # React가 붙는 루트 HTML (<div id="root">)
├─ package.json           # 프로젝트 의존성, 실행 스크립트
├─ vite.config.ts         # Vite 개발 서버/빌드 설정
├─ tsconfig.json          # TypeScript 기본 설정
├─ tsconfig.app.json      # 앱 코드 전용 TS 설정
├─ tsconfig.node.json     # Node 환경용 TS 설정
├─ .gitignore             # Git에 올리지 않을 파일/폴더
├─ README.md              # 프로젝트 설명 문서
├─ yarn.lock / package-lock.json # 의존성 버전 고정 파일

권장 구조의 실행 흐름

간단한 실행 흐름을 정리해 보았다(참고용)

1. 프로젝트 환경 준비

package.json
→ 프로젝트 의존성(react, react-dom, vite, typescript 등)을 정의
→ scripts (dev, build, preview) 명령어도 여기서 실행됨

yarn.lock / package-lock.json
→ 협업 시 동일한 버전의 패키지가 설치되도록 보장

2. 앱의 진입점

Index.html
→ 브라우저가 처음 여는 HTML 파일
→ <div id="root"></div> 만 포함 -> React가 이 root에 마운트됨
main.tsx
→ App.tsx를 index.html의 root에 마운트
→ index.css 전역 스타일 적용

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

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

3. 앱의 최상위 컴포넌트

src / App.tsx
→ 프로젝트 전체를 감싸는 최상위 컴포넌트
→ 여기서 components/ 폴더에 있는 UI 컴포넌트를 불러와 화면을 구성한다.
src / components
→ UI 단위들을 분리해서 관리한다.
→ App.tsx 또는 다른 페이지 컴포넌트에서 조립해서 화면을 구성한다.

4. 개발 / 빌드 과정

vite.config.ts
→ 개발 서버(yarn dev) 실행 시 Vite가 참고하는 설정 파일이다.
→ 경로 별칭(@/components), 플러그인, 빌드 옵션 등을 정의한다!
tsconfig.json / tsconfig.app.json / tsconfig.node.json
→ TypeScript가 코드 타입 검사 및 빌드 시 참고하는 규칙을 정의한다.
- tsconfig.json → 기본 설정
- tsconfig.app.json → src/ 내부 코드용
- tsconfig.node.json → Node 환경용

tsconfig.json	공통 / 루트	직접 코드에는 적용 X → 다른 tsconfig를 extends 또는 references	관리자 역할: 프로젝트 전체 공통 설정 모음앱/Node 설정을 묶는 루트
tsconfig.app.json	브라우저 (React 앱)	src/ 내부 코드 (컴포넌트, 로직 등)	앱 코드 전용: 브라우저 실행 코드용 TS 옵션React, JSX 관련 설정 포함
tsconfig.node.json	Node (개발 도구)	Node 환경에서 실행되는 파일 (예: vite.config.ts)	Node 전용: 설정 파일에서 Node API 사용 가능브라우저 코드와 분리 관리

5. 기타 관리 파일

.gitignore
→ GitHub 등 저장소에 올리지 않을 파일/폴더(node_modules, dist 등) 지정
README.md
→ 프로젝트 소개, 설치 방법, 실행 방법 문서

Question : 위 과정에서 생긴 궁금증

TypeScript와 TypeScript + SWC의 차이점이 뭘까?

TypeScript는 타입 검사와 트랜스파일을 함께 하지만 느린 편이고, TypeScript + SWC는 타입 검사는 따로 하고 트랜스파일만 초고속으로 처리

SWC는 자바스크립트 프로젝트의 컴파일과 번들링 모두에 사용될 수 있는, Rust라는 언어로 제작된 빌드 툴이라고 한다.

SWC는 Speedy Web Compiler의 약자로, 말 그대로 매우 빠른 웹 컴파일러의 기능을 제공하는 툴이다.

이 툴이 빠른 이유는 Rust라는 프로그래밍 언어가 이벤트 루프 기반의 싱글 스레드 언어인 자바스크립트와는 다르게 병렬 처리를 고려해서 설계된 언어이기 때문이다.

SWC 옵션을 쓰는 게 대부분 권장 (Next.js, Vite 같은 최신 프레임워크도 기본값으로 채택 중)
이유는 빌드·핫리로드 속도가 훨씬 빠르기 때문이다!
단, SWC는 타입 검사를 하지 않으니 → 보통 tsc --noEmit을 CI나 별도 프로세스에서 돌려서 타입 안정성은 유지하도록.

*번들링 : 빌드 과정 중 하나로, 웹 개발에서 여러 개의 자바스크립트 파일을 하나 또는 소수의 파일로 합치는 과정.

* Rust : Mozilla가 개발한 시스템 프로그래밍 언어이다. 속도가 빠르고, 메모리 안전성이 뛰어나 대규모 코드 트랜스파일·번들링 같은 무거운 작업을 자바스크립트보다 훨씬 효율적으로 처리할 수 있음.

tsconfig.node.json 파일을 따로 두는 이유가 무엇인가? : Node환경이란

1. Node 환경이란?

Node.js 환경은 브라우저가 아닌 곳에서 자바스크립트를 실행할 수 있도록 해주는 런타임을 말합니다.

브라우저 환경
- DOM, Window, Document 같은 객체가 있음
- alert(), document.querySelector() 같은 함수 사용 가능
Node.js 환경
- 서버, CLI 도구, 빌드 스크립트 실행 시 사용
- require(), import fs from 'fs', process.env 같은 Node 전용 기능 사용 가능
- DOM API 없음 (브라우저 전용이니까)

2. tsconfig.node.json을 따로 두는 이유

TypeScript 프로젝트에서는 환경별로 필요한 설정이 다르다.
React 같은 브라우저 실행 환경과, Vite 설정 파일(vite.config.ts)이나 ESLint 설정처럼 Node.js 실행 환경이 다르기 때문이에요.

tsconfig.app.json
→ src/ 안에 있는 애플리케이션 코드(브라우저에서 실행됨)를 위한 설정
→ 브라우저 전용 API (DOM, fetch 등) 타입이 필요
tsconfig.node.json
→ Node.js에서 실행되는 파일(vite.config.ts, scripts/, 백엔드 코드 등)을 위한 설정
→ Node 전용 API (fs, path, process, __dirname 등) 타입이 필요

>> 즉, Node 환경에서 돌릴 코드와 브라우저 환경에서 돌릴 코드가 구분되기 때문에, 타입 정의와 설정을 분리해서 관리하는 것이다.

회고

프로젝트를 만들 때의 조합을 정리해보니 프로젝트 구성과 각 파일의 역할에 대해서 더 잘 이해할 수 있게 된 것 같다!

이제 본격적으로 프로젝트와 프론트 공부를 시작해보자!

'React' 카테고리의 다른 글

[React] useContext 활용하기 (0)	2025.09.26
[React] React가 무엇일까? (3)	2025.09.08