Vite + React + TailwindCSS 프로젝트 구성 가이드

2025년 2월, React 팀은 Create React App(CRA)의 공식 지원 종료를 발표하며, 개발자들에게 Vite, Parcel, RSBuild와 같은 최신 빌드 도구로의 마이그레이션을 권장하고 있습니다. CRA는 오랜 기간 React 입문자들에게 널리 사용되어 왔지만, 설정의 복잡성과 느린 빌드 속도 등의 한계로 인해 점차 대체되고 있습니다. 그중에서도 Vite는 빠른 번들링 속도와 즉각적인 모듈 핫 리로딩(HMR), 그리고 Tailwind CSS와의 뛰어난 통합성으로 많은 개발자들의 선택을 받고 있습니다.

이 글에서는 React를 처음 시작하는 사용자를 대상으로, Vite + React + Tailwind CSS 조합으로 프로젝트 초기 환경을 구성하는 방법을 안내합니다.

1. 개발 환경 구성

React는 브라우저에서 실행되는 프론트엔드 애플리케이션이지만, 개발 및 빌드 과정에서는 다양한 JavaScript 도구와 패키지 관리자가 필요합니다. 이 과정에 필요한 핵심 도구가 바로 Node.js, npm, npx입니다.

  • Node.js: JavaScript를 브라우저 밖, 서버 환경에서 실행할 수 있게 해주는 런타임
  • npm (Node Package Manager):React, Vite, Tailwind 등 외부 패키지를 설치하고 관리하는 도구(ex. npm create vite@latest)
  • npx: 패키지를 전역(global)이나 로컬(node_modules)에 설치하지 않고 실행하는 도구(ex. npx cowsay Hello!)

Node.js 설치는 유연한 버전 관리를 위해 NVM(Node Version Manager)을 사용하겠습니다. NVM을 사용하면 여러 Node.js 버전을 쉽게 설치하고 전환할 수 있어, 프로젝트마다 적절한 버전을 유지하는 데 매우 유용합니다.

이 가이드는 macOS 환경을 기준으로 작성되었습니다. Linux와 Windows 사용자는 각 운영체제에 맞는 NVM 설치 방법을 참고하시기 바랍니다.

NVM 설치
brew를 사용하여 nvm를 설치합니다.

brew install nvm
mkdir ~/.nvm

~/.zshrc 또는 ~/.bashrc 파일에 아래를 추가합니다:

export NVM_DIR=~/.nvm
source $(brew --prefix nvm)/nvm.sh

nvm을 사용하여 Node.js 설치하고 기본 설정하겠습니다.

nvm install --lts             # LTS 버전 설치
nvm alias default lts         # 기본 버전 설정
# nvm install 17.5.0          # 특정 버전 설치
# nvm use 17.5.0              # 현재 터미널에서 특정 버전 사용

Node.js, npm, npx가 제대로 설치되었는지 버전을 확인하세요.

node -v   # v22.16.0
npm -v    # 10.9.2
npx -v    # 10.9.2

2. Vite 기반 React 프로젝트 생성

프로젝트 생성
Vite React 템플릿을 사용하여 빠르게 프로젝트를 생성하고 의존성을 설치합니다.

npm create vite@latest vite-react -- --template react-ts
cd vite-react
npm install

이글을 작성하고 있는 시점의 vite@latest 버전은 7.1.1입니다.(2025-08-08)

프로젝트 구조
Vite로 프로젝트 초기 구성을 한 이후, 이 가이드에서 추가, 변경, 삭제되는 주요 파일 및 폴더는 다음과 같습니다.

.
├── Dockerfile                # 도커 이미지 빌드 설정 파일 (신규)
├── eslint.config.js          # ESLint 설정 파일
├── index.html                # 기본 HTML 템플릿 (변경)
├── Makefile                  # 빌드 및 실행 자동화 스크립트 (신규)
├── node_modules              # 프로젝트 의존성 모듈 폴더
├── package-lock.json         # 의존성 버전 잠금 파일
├── package.json              # 프로젝트 의존성 및 스크립트 관리 파일
├── postcss.config.js         # PostCSS 설정 파일
├── public                    # 정적 리소스 폴더
│   ├── env.js                # 환경 변수 설정 파일 (신규)
│   └── vite.svg              # Vite 로고 이미지 (신규)
├── README.md                 # 프로젝트 설명 문서 (신규)
├── src                       # 소스 코드 폴더
│   ├── App.tsx               # 메인 React 컴포넌트 (변경)
│   ├── App.css               # 앱 전용 CSS 파일 (제거)
│   ├── assets                # 정적 자원
│   │   └── react.svg         # React 로고 이미지
│   ├── components            # 재사용 컴포넌트 모음 (신규)
│   │   └── CounterBox.jsx    # 카운터 박스 컴포넌트 (신규)
│   ├── config.js             # 환경변수 및 설정 모듈 (신규)
│   ├── index.css             # 글로벌 CSS (변경)
│   ├── main.tsx              # React 앱 진입점
│   └── vite-env.d.ts         # Vite 타입 정의 파일
├── tailwind.config.js        # TailwindCSS 설정 파일 (변경)
├── tsconfig.app.json         # 앱 전용 TypeScript 컴파일러 옵션 (변경)
├── tsconfig.json             # 전체 프로젝트 TypeScript 컴파일러 옵션
├── tsconfig.node.json        # Node.js 환경용 TypeScript 설정 (신규)
└── vite.config.ts            # Vite 빌드 및 개발 서버 설정 파일

TypeScript 컴파일 설정
VSCode를 사용할 경우, TypeScript가 JavaScript 파일을 컴파일 대상에 포함시키고, JavaScript 파일 내 타입 검사를 비활성화하기 위해 tsconfig.app.json에 다음 설정을 추가합니다.

"compilerOptions": {
  "allowJs": true,
  "checkJs": false,
       :
}

3. Tailwind CSS 통합 및 스타일링

Tailwind CSS 설치
TailwindCSS와 필수 PostCSS 플러그인을 설치하고, 초기 설정 파일을 생성합니다.

npm i -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init -p

Tailwind 콘텐츠 파일 경로 설정
tailwind.config.js 파일에 Tailwind가 스타일을 적용할 파일 경로를 지정하여, 빌드 시 필요한 CSS만 포함되도록 합니다.

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Tailwind CSS 스타일 구성
src/index.css 파일의 기본 스타일을 Tailwind CSS로 대체합니다.

@tailwind base;
@tailwind components;
@tailwind utilities;

이 프로젝트는 Tailwind CSS만으로 UI를 구성하기 때문에, src/App.css 파일과 App.tsx 내의 해당 CSS import 구문을 제거합니다.

4. App.tsx 구조 개선

Vite 템플릿으로 생성된 App.tsx는 별도의 하위 컴포넌트 없이 로직과 UI가 하나의 파일에 함께 정의된 단순한 구조를 가지고 있습니다.

이러한 단순한 구조에서 컴포넌트, 환경 변수 설정, 그리고 Tailwind CSS 적용하여 프로젝트 구조를 보다 체계적이고 확장 가능한 형태로 개선하는 방법에 대해 알아보겠습니다.

컴포넌트 생성
src/App.tsx에서 counter 관련 코드를 분리하여 src/components 폴더에 CounterBox.jsx 파일로 만들고 해당 컴포넌트에 Tailwind CSS를 적용합니다.

import React from 'react'

function CounterBox({ count, setCount }) {
  const handleClick = () => setCount((prev) => prev + 1)

  return (
    <div className="bg-white shadow-md rounded-lg p-6 text-center">
      <button
        onClick={() => handleClick(setCount)}
        className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 transition-colors"
      >
        count is {count}
      </button>
      <p>This button increases the counter each time you click it.</p>
    </div>
  )
}

export default CounterBox

환경 변수 설정
React 앱을 컨테이너로 개발 또는 운영 환경에 배포할 때, 설정되는 환경 변수를 오버라이드할 수 있도록 public/env.js 파일을 생성하고 환경변수를 추가합니다.

window._env_ = {
  VITE_REACT_TITLE: "Vite + React + Tailwind CSS"
}

index.html의 body 태그에 public/env.js 스크립트를 추가합니다.

  <body>
    <div id="root"></div>
    <script src="/env.js"></script>
    <script type="module" src="/src/main.tsx"></script>
  </body>

src/config.js를 소스 디렉토리에 생성하고 .env에서 환경변수 값을 읽어옵니다.

export const APP_TITLE = window._env_.VITE_REACT_TITLE || 'Default App Title';

환경 변수 설정을 위해 .env를 사용하지 않고 이렇게 구성하는 이유는 React가 빌드 시점에 .env 파일의 환경변수를 정적으로 주입하기 때문에, 런타임에 .env 파일을 변경할 수 없는 한계를 극복하기 위함입니다. public/env.js 방식은 빌드 후에도 컨테이너 실행 시점에 환경변수를 동적으로 변경할 수 있어 유연성을 제공합니다. 하지만, 보안 및 관리 측면을 고려하여 신중하게 결정해야 합니다.

App.tsx 개선
기존의 src/App.tsx에 CounterBox 컴포넌트, 환경 변수,Tailwind CSS을 적용합니다.

import { useState } from 'react'
import reactLogo from './assets/react.svg'
import viteLogo from '/vite.svg'
import { APP_TITLE } from './config'
import CounterBox from './components/CounterBox'

function App() {
  const [count, setCount] = useState(0)

  return (
    <div className="min-h-screen bg-gray-100 flex flex-col items-center justify-center p-4">
      <div className="flex space-x-8 mb-6">
        <a href="https://vite.dev" target="_blank" rel="noreferrer">
          <img src={viteLogo} className="w-24 h-24 transition-transform hover:scale-110" alt="Vite logo" />
        </a>
        <a href="https://react.dev" target="_blank" rel="noreferrer">
          <img src={reactLogo} className="w-24 h-24 transition-transform hover:scale-110" alt="React logo" />
        </a>
      </div>

      <h1 className="text-4xl font-bold text-gray-800 mb-4">{APP_TITLE}</h1>
      <CounterBox count={count} setCount={setCount} />

      <p className="mt-4 text-gray-600">
        Edit <code className="bg-gray-200 px-1 py-0.5 rounded">src/App.tsx</code> and save to test HMR
      </p>
      <p className="mt-8 text-sm text-gray-500">
        Click on the Vite and React logos to learn more
      </p>
    </div>
  )
}

export default App

4. React 앱 실행

vite-react 프로젝트 구성을 마쳤다면, React 앱을 실행하여 UI 구성과 기능이 정상적으로 동작하는지 브라우저에서 확인할 수 있습니다.

npm run dev

브라우저에서 http://localhost:5173 접속합니다.

5. 이미지 빌드 및 실행

Kubernetes와 같은 개발환경에 React 앱을 배포하기 위해 컨테이너 이미지로 빌드하고 실행해 봅니다.

Dockerfile
로컬에서 React 앱을 개발하고 테스트를 마친 소스를 가지고, 이미지를 빌드하기 위한 Dockerfile을 구성합니다.

# Build Stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
COPY tsconfig.* ./
COPY vite.config.* ./
COPY tailwind.config.* ./
COPY postcss.config.* ./
COPY .env* ./
COPY src ./src
COPY public ./public
COPY index.html ./
RUN npm ci && npm run build

# Production Stage
FROM nginx:alpine
WORKDIR /usr/share/nginx/html
COPY --from=builder /app/dist .
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

환경변수 오버라이드
프로젝트 루트에 env-dev.js 파일을 생성하여 환경변수를 재정의합니다.

VITE_REACT_TITLE=Vite + React + Tailwind CSS + Docker

Makefile
Makefile을 만들어 이미지 빌드, 실행, 푸쉬하는 반복 작업을 단순화합니다.

IMAGE_NAME=vite-react
TAG=latest

.PHONY: build run push clean

build:
	docker build -t $(IMAGE_NAME):$(TAG) .

PWD := $(shell pwd)

build:
	docker build -t $(IMAGE_NAME):$(TAG) .

run:
	docker run -p 8080:80 \
	-v $(PWD)/env-dev.js:/usr/share/nginx/html/env.js \
	$(IMAGE_NAME):$(TAG)

push:
	docker push $(IMAGE_NAME):$(TAG)

clean:
	docker rmi $(IMAGE_NAME):$(TAG) || true

Makefile을 사용하여 React 앱 이미지를 빌드하고 실행합니다.

make build
make run

이제 브라우저에 http://localhost:8080에 접속하여 정상적으로 기능이 동작하는지 확인해봅니다.

6. VSCode에서 디버깅 환경 설정

VSCode에서 디버깅하려면, 먼저 React 앱을 실행한 상태에서 VSCode와 Chrome을 연동하는 디버깅 환경을 설정해야 합니다.

React 앱 실행

npm run dev

launch.json 설정
.vscode/launch.json 파일에 아래 내용을 추가합니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome against Vite",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/src"
    }
  ]
}

디버깅 실행
VSCode에서 Run and Debug 뷰를 열고 “Launch Chrome against Vite” 구성 선택하고 Start Debugging (F5) 클릭하면 Chrome이 자동 실행되고 디버깅이 가능합니다.

dnsmasq web ui

7. 마무리

이번 가이드에서는 React, Vite, TailwindCSS를 조합해 빠르고 효율적인 프론트엔드 프로젝트를 구성하는 기본 흐름을 살펴보았습니다. 처음 React를 시작하는 사용자를 대상으로 환경 구성, 프로젝트 생성 및 템플릿 개선, 컨테이너 빌드, 디버깅을 하는 방법애 대해 다루었습니다.

이처럼 Vite를 사용하여 React 프로젝트의 초기 환경을 안정적으로 구성하고 업무 기능과 UI를 추가하며 프로젝트를 확장해 나갈 수 있습니다.

🔗 참고 링크