Engineering

Vite를 이용한 React 프로젝트 설정 가이드

Vite를 이용한 React 프로젝트 설정 가이드 학습 내용을 정리한 백필 노트입니다.

이 글은 2025년 학습 기록을 블로그 형식으로 정리한 백필 노트입니다.

이 문서는 빌드 도구인 Vite를 사용하여 JavaScript 또는 TypeScript 기반의 React 프로젝트를 시작하고, 코드 품질 및 개발 편의성을 높이기 위한 초기 설정 방법을 안내합니다.

1. Vite 프로젝트 생성

사전 조건: Node.js 18+, NPM 8+ 버전이 설치되어 있어야 합니다.

템플릿으로 빠른 시작 (권장)

미리 구성된 템플릿을 사용하여 프로젝트를 빠르게 시작할 수 있습니다.

Bash

# 현재 폴더에 React+TS 템플릿 복사
npx degit ParkYoungWoong/vite-template--react-ts .

# 패키지 설치
npm i

# 개발 서버 실행
npm run dev

직접 생성 및 설정

Vite CLI를 통해 프로젝트를 직접 생성합니다.

프로젝트 생성
- 현재 폴더에 생성: npm create vite@latest .
- 새 폴더에 생성: npm create vite@latest <프로젝트_폴더_이름>
- 프롬프트에서 React와 JavaScript + SWC 또는 TypeScript + SWC를 선택합니다.

의존성 설치 및 실행Bash

# (새 폴더에 생성한 경우) 프로젝트 폴더로 이동
cd <프로젝트_폴더_이름>

# 의존성 패키지 설치
npm i

# 개발 서버 실행
npm run dev

2. ESLint와 Prettier 연동

코드 품질(ESLint)과 코드 스타일(Prettier)을 일관되게 관리하기 위해 연동합니다.

VS Code 확장 프로그램 설치

ESLint
Prettier - Code formatter

개발 의존성 패키지 설치

프로젝트의 devDependencies로 관련 패키지를 설치합니다.

**JavaScript 프로젝트의 경우:**Bash

npm i -D eslint prettier eslint-plugin-react eslint-config-prettier eslint-plugin-prettier

**TypeScript 프로젝트의 경우:**Bash

npm i -D eslint prettier eslint-plugin-react eslint-config-prettier eslint-plugin-prettier @typescript-eslint/eslint-plugin @typescript-eslint/parser

설정 파일 생성 및 구성

.eslintrc.json (ESLint 설정 파일)

프로젝트 루트에 생성하고, Prettier와의 충돌 방지 플러그인을 extends 배열 마지막에 추가합니다.JSON

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended", // TS인 경우
    "plugin:react/recommended",
    "plugin:prettier/recommended" // 마지막에 추가
  ]
}

.prettierrc (Prettier 설정 파일)
- 프로젝트 루트에 생성하여 원하는 코드 스타일 규칙을 정의합니다.JSON
```
{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true
  // ...기타 규칙
}
```

VS Code 자동 포맷팅 설정

파일 저장 시 자동으로 코드 스타일이 적용되도록 settings.json에 설정합니다.

ESLint 자동 수정 (전역 또는 지역 설정)
- 파일 저장 시 ESLint 규칙에 따라 자동 수정되도록 설정합니다.JSON
```
// settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}
```
Prettier 자동 포맷팅 (프로젝트 지역 설정 권장)
- 프로젝트 루트에 .vscode/settings.json 파일을 생성하여 설정합니다.JSON
```
// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}
```

3. 경로 별칭(Path Alias) 구성

복잡한 상대 경로(../../components) 대신 절대 경로 기반의 별칭(@/components)을 사용하여 가독성과 유지보수성을 높입니다.

vite.config.ts 설정

resolve.alias 옵션을 추가하여 별칭을 정의합니다.TypeScript

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
  resolve: {
    alias: [{ find: '@', replacement: '/src' }]
  }
})

tsconfig.app.json 설정 (TypeScript 프로젝트)
- Vite에서 설정한 별칭을 TypeScript가 인식할 수 있도록 compilerOptions에 baseUrl과 paths를 추가합니다.JSON
```
// tsconfig.app.json
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```