React 프로젝트 : Node.js 와 Vite 기반 구축 및 팀원 설치 가이드

Node.js와 Vite로 React 프로젝트 설정 가이드

Node.js와 Vite를 사용하여 React 프로젝트를 설정하고, 팀원들이 동일한 환경에서 작업할 수 있도록 돕는 실무적인 가이드를 제공합니다. 이 글은 프로젝트 초기 설정부터 Docker를 활용한 환경 통일, 그리고 Windows 환경에서 발생할 수 있는 문제 해결 방법까지 다룹니다.

---

💡 개요

팀 프로젝트에서 동일한 개발 환경을 유지하는 것은 생산성 향상과 오류 감소의 핵심입니다. 특히, Node.js와 Vite 기반의 React 프로젝트에서는 아래 내용을 포함한 설정이 중요합니다:

• Node.js 버전 관리
• Vite 설정 최적화
• Docker를 활용한 일관된 개발 환경
• Windows 사용자 고려 사항

---

🚀 React 프로젝트 설정

1. Node.js 설치 및 버전 관리

프로젝트에 적합한 Node.js 버전을 사용하려면 nvm(Node Version Manager)을 활용하세요.

Mac/Linux

nvm install 16.14.0
nvm use 16.14.0

Windows

nvm-windows 설치 가이드를 참고하세요.

nvm install 16.14.0
nvm use 16.14.0

팀 환경 통일

.nvmrc 파일에 버전을 명시하세요:

echo "16.14.0" > .nvmrc

2. Vite로 React 프로젝트 생성

Vite는 React 프로젝트를 빠르고 간편하게 설정할 수 있는 도구입니다.

npm create vite@latest my-react-app -- --template react
cd my-react-app

3. 의존성 설치

npm ci를 사용해 팀 간 동일한 패키지 설치를 보장합니다.

npm ci

4. 개발 서버 실행

Vite 개발 서버를 실행하여 프로젝트를 시작합니다.

npm run dev

---

🔧 추가 설정

1. 환경 변수 추가

프로젝트에서 필요한 환경 변수를 설정하세요.

• .env 파일 생성:
  • VITE_API_URL=https://api.example.com
• 코드에서 환경 변수 참조:
  • console.log(import.meta.env.VITE_API_URL);

2. Vite 설정 변경

자주 사용하는 설정을 추가해 실무에서 효율적으로 활용할 수 있습니다.

Alias 설정: vite.config.js에 경로 별칭을 추가하세요

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

3. Node.js 버전 명시

package.json에 Node.js 버전을 명시하여 실행 환경을 명확히 합니다.

{
  "engines": {
    "node": ">=16.14.0"
  }
}

---

🐳 Docker를 활용한 환경 통일

Docker를 사용하면 팀원들이 동일한 개발 환경을 유지할 수 있습니다.

1. Dockerfile 작성

FROM node:16.14

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .

CMD ["npm", "run", "dev"]

2. Docker 빌드 및 실행

docker build -t my-react-app .
docker run -p 5173:5173 my-react-app

---

🖥️ Windows 환경 팁

Windows 사용자를 위한 추가 팁입니다.

1. nvm-windows 사용

nvm-windows를 설치하여 Node.js 버전을 관리하세요. 설치는 nvm-windows GitHub 페이지를 참고하세요.

2. 문제 해결: 파일 삭제 명령어

Windows에서 종종 node_modules를 삭제해야 할 때는 다음 명령어를 사용하세요:

rd /s /q node_modules
del package-lock.json
npm ci

---

❓ FAQ

1. Vite와 기존 CRA(Create React App)의 차이는 무엇인가요?

• Vite는 빠른 빌드와 개발 서버 성능을 제공합니다.
• CRA는 설정이 더 직관적이지만, 빌드 속도에서 뒤처질 수 있습니다.

2. npm install과 npm ci의 차이점은?

• npm install: package-lock.json을 무시하고 최신 버전 패키지를 설치할 수 있습니다.
• npm ci: package-lock.json을 엄격히 따르고, 설치 속도가 더 빠릅니다.

3. Docker를 사용해야 하는 이유는?

• 모든 팀원이 동일한 환경에서 작업할 수 있어 환경 차이로 인한 문제가 줄어듭니다.
• CI/CD 환경에서도 유용합니다.

4. 환경 변수는 어떻게 관리하나요?

• .env 파일을 사용하여 민감한 데이터를 관리합니다. .env 파일은 Git에 커밋하지 않도록 .gitignore에 추가하세요.

5. Windows와 Mac/Linux 간 설정 차이는?

• Windows에서는 파일 삭제 명령어와 경로 표현 방식이 다릅니다. 가이드를 참고하여 적합한 명령어를 사용하세요.

---

🏷️ 관련 태그

• nodejs
• react
• vite
• docker
• 개발환경-설정

---