이미지 로딩 중...
AI Generated
2025. 11. 19. · 2 Views
Vite 프로젝트 시작하기 완벽 가이드
이 가이드는 초급 개발자를 위한 Vite 프로젝트 시작 완벽 가이드입니다. Vite 설치부터 프로젝트 생성, 구조 이해, 기본 설정, 개발 서버 실행까지 실무에서 바로 활용할 수 있는 모든 과정을 단계별로 상세히 다룹니다. 초등학생도 이해할 수 있을 정도로 쉽고 친근하게 설명합니다.
목차
- Vite 설치 및 프로젝트 생성
- React, Vue, Svelte 템플릿 선택
- 프로젝트 구조 이해하기
- vite.config.js 기본 설정
- 개발 서버 실행 및 Hot Module Replacement 체험
- package.json 스크립트 구성
1. Vite 설치 및 프로젝트 생성
시작하며
여러분이 새로운 웹 프로젝트를 시작할 때 이런 상황을 겪어본 적 있나요? 개발 서버가 너무 느려서 코드를 수정할 때마다 몇 초씩 기다려야 하고, 빌드 시간이 너무 오래 걸려서 커피 한 잔 마시고 와야 하는 상황 말이에요.
이런 문제는 실제 개발 현장에서 정말 자주 발생합니다. 특히 프로젝트 규모가 커질수록 기존 빌드 도구들은 점점 느려지고, 개발자의 생산성도 함께 떨어지게 됩니다.
빠른 피드백이 중요한 개발 과정에서 이런 느린 속도는 큰 스트레스가 되죠. 바로 이럴 때 필요한 것이 Vite입니다.
Vite는 마치 번개처럼 빠른 속도로 개발 서버를 실행하고, 여러분이 코드를 수정하면 즉시 화면에 반영해줍니다. 이제 기다림 없이 바로바로 결과를 확인하면서 개발할 수 있습니다.
개요
간단히 말해서, Vite는 여러분의 웹 개발을 엄청나게 빠르게 만들어주는 최신 빌드 도구입니다. 마치 자전거를 타다가 고속 열차로 갈아탄 것처럼 개발 속도가 확 달라집니다.
왜 이렇게 빠른지 궁금하시죠? Vite는 최신 브라우저가 지원하는 ES 모듈이라는 기술을 활용합니다.
예를 들어, 여러분이 100개의 파일로 이루어진 프로젝트를 만들 때, 기존 도구들은 모든 파일을 하나로 합쳐야 했지만, Vite는 필요한 파일만 필요할 때 가져오기 때문에 서버 시작이 1초도 안 걸립니다. 기존에는 프로젝트를 시작하려면 복잡한 webpack 설정 파일을 만들고 수많은 플러그인을 설치해야 했다면, 이제는 한 줄의 명령어로 모든 설정이 자동으로 완료됩니다.
Vite의 핵심 특징은 세 가지입니다. 첫째, 개발 서버가 번개처럼 빠르게 시작됩니다.
둘째, 코드를 수정하면 즉시 화면에 반영됩니다(Hot Module Replacement). 셋째, 실제 배포할 때는 Rollup이라는 검증된 도구로 최적화된 빌드를 만들어줍니다.
이러한 특징들이 여러분의 개발 경험을 완전히 바꿔놓을 것입니다.
코드 예제
# Node.js가 설치되어 있는지 확인 (버전 14.18+ 또는 16+ 필요)
node -v
# npm을 사용하여 Vite 프로젝트 생성
npm create vite@latest my-first-vite-app
# 또는 pnpm 사용 (더 빠른 패키지 관리자)
pnpm create vite my-first-vite-app
# 또는 yarn 사용
yarn create vite my-first-vite-app
# 프로젝트 폴더로 이동
cd my-first-vite-app
# 필요한 패키지들을 설치
npm install
# 개발 서버 실행 - 이제 코딩을 시작할 준비 완료!
npm run dev
설명
이것이 하는 일: 위 명령어들은 여러분의 컴퓨터에 Vite 기반의 새로운 웹 프로젝트를 만들어줍니다. 마치 레고 블록으로 집을 지을 때 기본 틀을 먼저 만드는 것처럼, Vite가 프로젝트의 기본 구조를 자동으로 세팅해주는 거예요.
첫 번째로, node -v 명령어로 Node.js가 설치되어 있는지 확인합니다. Node.js는 여러분의 컴퓨터에서 JavaScript를 실행할 수 있게 해주는 프로그램이에요.
마치 게임을 하려면 게임기가 필요한 것처럼, Vite를 사용하려면 Node.js가 필요합니다. 버전 14.18 이상이 설치되어 있어야 하며, 만약 없다면 nodejs.org에서 다운로드할 수 있습니다.
두 번째로, npm create vite@latest my-first-vite-app 명령어를 실행하면 Vite가 자동으로 프로젝트를 생성합니다. 여기서 'my-first-vite-app'은 여러분이 원하는 프로젝트 이름으로 바꿀 수 있어요.
이 명령어를 실행하면 Vite가 "어떤 프레임워크를 사용하시겠어요?"라고 물어봅니다. React, Vue, Svelte 등 원하는 것을 선택하면 됩니다.
세 번째로, cd my-first-vite-app으로 새로 만든 프로젝트 폴더로 이동하고, npm install을 실행합니다. 이 과정은 프로젝트에 필요한 모든 라이브러리들을 인터넷에서 다운로드해서 설치하는 과정이에요.
마치 요리를 하기 전에 필요한 재료들을 마트에서 사오는 것과 같습니다. 마지막으로, npm run dev를 실행하면 개발 서버가 시작됩니다.
보통 http://localhost:5173 주소로 접속할 수 있으며, 이 주소를 브라우저에 입력하면 여러분의 첫 Vite 프로젝트를 볼 수 있습니다. 이제부터 코드를 수정하면 저장만 해도 브라우저에 즉시 반영되는 마법 같은 경험을 하실 수 있습니다.
여러분이 이 명령어들을 사용하면 복잡한 설정 없이 단 5분 만에 최신 개발 환경을 갖출 수 있습니다. 기존 방식보다 10배 이상 빠른 개발 서버, 자동으로 최적화된 빌드 설정, 그리고 즉각적인 피드백을 통해 훨씬 즐겁게 개발할 수 있게 됩니다.
실전 팁
💡 Node.js 버전이 낮다면 nvm(Node Version Manager)을 사용해서 여러 버전을 쉽게 관리할 수 있습니다. nvm을 설치하면 nvm install 18 같은 명령어로 최신 버전을 바로 설치할 수 있어요.
💡 프로젝트 이름에는 공백이나 특수문자 대신 하이픈(-)이나 언더스코어(_)를 사용하세요. 예를 들어 'my-awesome-app'처럼 작성하면 나중에 배포할 때 문제가 생기지 않습니다.
💡 npm 대신 pnpm을 사용하면 패키지 설치 속도가 훨씬 빠르고 디스크 공간도 절약됩니다. npm install -g pnpm으로 설치한 후 사용해보세요.
💡 개발 서버를 실행할 때 포트 번호를 바꾸고 싶다면 npm run dev -- --port 3000 명령어를 사용하세요. 여러 프로젝트를 동시에 띄울 때 유용합니다.
💡 프로젝트를 생성할 때 --template react-ts 옵션을 추가하면 TypeScript가 미리 설정된 프로젝트를 만들 수 있습니다. 예: npm create vite@latest my-app -- --template react-ts
2. React, Vue, Svelte 템플릿 선택
시작하며
여러분이 Vite 프로젝트를 처음 만들 때 이런 고민을 해본 적 있나요? "React, Vue, Svelte...
도대체 뭘 선택해야 하지? 각각 어떻게 다른 거지?" 라는 생각 말이에요.
이런 선택은 정말 중요합니다. 왜냐하면 프레임워크를 선택하는 것은 마치 여행을 갈 때 교통수단을 선택하는 것과 같거든요.
비행기, 기차, 자동차 모두 목적지에 갈 수 있지만, 각각의 장점과 특징이 다르죠. 잘못 선택하면 나중에 프로젝트를 처음부터 다시 시작해야 할 수도 있습니다.
바로 이럴 때 필요한 것이 각 템플릿의 특징을 이해하는 것입니다. Vite는 여러분이 원하는 프레임워크를 쉽게 선택할 수 있도록 미리 준비된 템플릿을 제공합니다.
각 템플릿의 특징을 알고 선택하면 프로젝트 시작부터 완성까지 훨씬 수월합니다.
개요
간단히 말해서, Vite 템플릿은 여러분이 선택한 프레임워크에 맞는 프로젝트 기본 구조를 자동으로 만들어주는 시작점입니다. 마치 요리할 때 레시피북을 고르는 것처럼, 어떤 방식으로 개발할지 선택하는 거예요.
왜 템플릿이 필요한지 궁금하시죠? 각 프레임워크마다 설정 방법, 파일 구조, 개발 방식이 완전히 다릅니다.
예를 들어, React는 JSX라는 특별한 문법을 사용하고, Vue는 .vue 파일을 사용하며, Svelte는 컴파일 방식이 다릅니다. 템플릿을 사용하면 이런 복잡한 설정을 고민할 필요 없이 바로 코딩을 시작할 수 있어요.
기존에는 create-react-app이나 vue-cli처럼 각 프레임워크마다 별도의 CLI 도구를 사용해야 했다면, 이제는 Vite 하나로 모든 프레임워크 프로젝트를 만들 수 있습니다. Vite가 제공하는 주요 템플릿은 다음과 같습니다.
vanilla(순수 JavaScript), vanilla-ts(TypeScript), vue, vue-ts, react, react-ts, react-swc-ts, preact, svelte, svelte-ts, lit, lit-ts, solid, solid-ts, qwik 등 정말 다양합니다. 여기서 '-ts'가 붙은 것은 TypeScript를 사용하는 템플릿이고, 없는 것은 일반 JavaScript를 사용하는 템플릿입니다.
이렇게 많은 선택지를 제공함으로써 여러분은 자신에게 가장 편한 도구를 선택할 수 있습니다.
코드 예제
# Vite 프로젝트 생성 시작 - 대화형 방식
npm create vite@latest
# 프로젝트 이름 입력: my-react-app
# 프레임워크 선택: React 선택
# 변형 선택: TypeScript 선택
# 또는 명령어 한 줄로 React + TypeScript 프로젝트 생성
npm create vite@latest my-react-app -- --template react-ts
# Vue 3 + TypeScript 프로젝트 생성
npm create vite@latest my-vue-app -- --template vue-ts
# Svelte + TypeScript 프로젝트 생성
npm create vite@latest my-svelte-app -- --template svelte-ts
# 생성된 프로젝트로 이동하여 의존성 설치 및 실행
cd my-react-app && npm install && npm run dev
설명
이것이 하는 일: 위 명령어들은 여러분이 원하는 프레임워크로 프로젝트를 생성하는 다양한 방법을 보여줍니다. 마치 음식점에서 메뉴를 주문하는 것처럼, 여러분이 원하는 프레임워크를 선택하면 Vite가 그에 맞는 프로젝트를 만들어줍니다.
첫 번째로, npm create vite@latest를 옵션 없이 실행하면 대화형 방식으로 진행됩니다. 먼저 프로젝트 이름을 물어보고, 그 다음 화살표 키로 프레임워크를 선택할 수 있는 예쁜 메뉴가 나타납니다.
이 방식은 처음 사용하는 분들에게 가장 친절한 방법이에요. 각 선택지를 천천히 보면서 결정할 수 있거든요.
두 번째로, --template 옵션을 사용하면 대화형 과정을 건너뛰고 한 번에 원하는 템플릿으로 프로젝트를 만들 수 있습니다. 예를 들어 --template react-ts는 React와 TypeScript가 함께 설정된 프로젝트를 만듭니다.
이 방식은 이미 어떤 프레임워크를 사용할지 결정한 경우에 시간을 절약할 수 있어요. 특히 회사에서 여러 프로젝트를 반복해서 만들 때 자동화 스크립트에 넣어두면 정말 편리합니다.
세 번째로, 각 템플릿의 차이를 이해하는 것이 중요합니다. 'react-ts'는 React 18과 TypeScript가 미리 설정되어 있고, 'vue-ts'는 Vue 3의 Composition API와 TypeScript가 준비되어 있으며, 'svelte-ts'는 Svelte의 최신 버전과 TypeScript가 설정되어 있습니다.
각각의 템플릿은 해당 프레임워크의 공식 권장 사항을 따르고 있어서 안심하고 사용할 수 있습니다. 네 번째로, && 연산자를 사용하면 여러 명령어를 한 번에 실행할 수 있습니다.
cd my-react-app && npm install && npm run dev는 폴더로 이동하고, 패키지를 설치하고, 개발 서버를 실행하는 세 가지 작업을 자동으로 순서대로 진행합니다. 이렇게 하면 명령어를 하나씩 입력할 필요가 없어서 정말 편리해요.
여러분이 이 템플릿들을 사용하면 각 프레임워크의 최신 버전과 권장 설정이 자동으로 적용됩니다. React를 선택하면 React 18의 새로운 기능들이, Vue를 선택하면 Vue 3의 Composition API가, Svelte를 선택하면 Svelte의 반응형 시스템이 바로 사용 가능한 상태로 준비됩니다.
또한 TypeScript를 선택하면 타입 체크, 자동완성, 리팩토링 도구 등 개발 생산성을 높여주는 모든 기능이 함께 제공됩니다.
실전 팁
💡 처음 시작한다면 react-ts를 추천합니다. React는 가장 많은 자료와 커뮤니티를 가지고 있어서 문제가 생겼을 때 해결하기 쉽고, TypeScript는 코드를 작성할 때 실수를 미리 잡아줘서 버그를 줄일 수 있습니다.
💡 Vue를 선택할 때는 꼭 vue-ts를 사용하세요. Vue 3는 TypeScript와 함께 사용하도록 설계되었고, Composition API의 타입 추론이 정말 강력합니다. ref(), computed() 같은 함수들의 타입이 자동으로 잡혀서 개발이 훨씬 편해요.
💡 작은 프로젝트나 빠른 프로토타입이 필요하다면 Svelte를 고려해보세요. 번들 크기가 작고 문법이 간결해서 배우기 쉽고, 성능도 뛰어납니다. 특히 모바일 웹이나 성능이 중요한 프로젝트에 적합합니다.
💡 템플릿을 선택한 후에도 필요한 라이브러리는 자유롭게 추가할 수 있습니다. 예를 들어 React 프로젝트에 상태 관리를 위한 Zustand, 스타일링을 위한 Tailwind CSS 등을 npm install 명령어로 언제든지 설치할 수 있어요.
💡 회사나 팀에서 자주 사용하는 설정이 있다면 커스텀 템플릿을 만들어두세요. GitHub에 템플릿 저장소를 만들어두고 npm create vite@latest my-app -- --template https://github.com/username/my-template 형태로 사용하면 팀 전체가 동일한 설정으로 프로젝트를 시작할 수 있습니다.
3. 프로젝트 구조 이해하기
시작하며
여러분이 처음 Vite 프로젝트를 열었을 때 이런 생각을 해본 적 있나요? "이 폴더들은 뭐고, 이 파일들은 뭐하는 건지...
어디서부터 시작해야 하지?" 라는 막막함 말이에요. 이런 혼란은 정말 자연스러운 겁니다.
프로젝트 구조를 모르면 어떤 파일을 수정해야 할지, 새 파일은 어디에 만들어야 할지 알 수 없어요. 마치 처음 가본 대형 쇼핑몰에서 길을 잃은 것처럼, 코드를 작성하는 것보다 파일을 찾는 데 더 많은 시간을 쓰게 됩니다.
이런 상황이 계속되면 개발 속도가 느려지고 실수도 많아집니다. 바로 이럴 때 필요한 것이 프로젝트 구조에 대한 명확한 이해입니다.
각 폴더와 파일이 어떤 역할을 하는지 알면, 여러분은 자신감 있게 코드를 작성하고 관리할 수 있습니다. Vite 프로젝트의 구조는 단순하고 직관적이라서 한번 이해하면 쉽게 기억할 수 있어요.
개요
간단히 말해서, Vite 프로젝트 구조는 여러분의 코드를 체계적으로 정리하는 설계도입니다. 마치 집을 지을 때 거실, 침실, 부엌이 각각의 역할이 있듯이, 프로젝트의 각 폴더도 명확한 목적을 가지고 있어요.
왜 구조를 이해하는 것이 중요할까요? 올바른 위치에 파일을 두어야 Vite가 제대로 빌드하고 최적화할 수 있습니다.
예를 들어, public 폴더의 파일들은 빌드 시 그대로 복사되지만, src 폴더의 파일들은 번들링되고 최적화됩니다. 이런 차이를 모르면 이미지가 안 보이거나 파일을 찾을 수 없다는 에러가 발생할 수 있어요.
기존의 복잡한 webpack 프로젝트는 수십 개의 설정 파일과 복잡한 폴더 구조를 가졌다면, Vite 프로젝트는 정말 간결합니다. 필요한 것만 딱 있어서 초보자도 쉽게 이해할 수 있죠.
Vite 프로젝트의 핵심 구조는 이렇습니다. 첫째, src/ 폴더는 여러분이 작성하는 모든 소스 코드가 들어갑니다.
둘째, public/ 폴더는 빌드 과정을 거치지 않고 그대로 복사될 정적 파일들이 위치합니다. 셋째, index.html은 프로젝트의 진입점으로 가장 먼저 로드되는 파일입니다.
이 세 가지만 이해해도 80%는 이해한 겁니다!
코드 예제
my-vite-app/
├── node_modules/ # npm으로 설치된 모든 라이브러리들이 여기에
├── public/ # 정적 파일 폴더 - 그대로 복사됨
│ └── vite.svg # 파비콘이나 로봇.txt 같은 파일들
├── src/ # 여러분의 소스 코드가 모두 여기에!
│ ├── assets/ # 이미지, 폰트 등 - 빌드 시 최적화됨
│ │ └── react.svg
│ ├── App.css # 컴포넌트 스타일
│ ├── App.tsx # 메인 컴포넌트
│ ├── index.css # 전역 스타일
│ └── main.tsx # 애플리케이션 진입점
├── .gitignore # Git이 무시할 파일 목록
├── index.html # HTML 진입점 - 중요!
├── package.json # 프로젝트 정보와 의존성 목록
├── tsconfig.json # TypeScript 설정
└── vite.config.ts # Vite 설정 파일
설명
이것이 하는 일: 이 구조는 여러분의 프로젝트 파일들을 목적에 따라 체계적으로 분류합니다. 마치 도서관에서 책을 장르별로 정리하는 것처럼, 각 파일을 적절한 위치에 배치하여 찾기 쉽고 관리하기 편하게 만듭니다.
첫 번째로, src/ 폴더는 여러분이 실제로 작성하는 모든 코드가 들어가는 곳입니다. main.tsx는 애플리케이션의 시작점으로, React의 경우 여기서 ReactDOM.render()를 호출해서 앱을 DOM에 마운트합니다.
App.tsx는 메인 컴포넌트로, 여러분이 만들 모든 페이지와 컴포넌트의 최상위 부모 역할을 합니다. 이 파일들을 수정하면 Vite가 자동으로 변경을 감지해서 즉시 브라우저에 반영해줍니다.
두 번째로, public/ 폴더는 특별한 역할을 합니다. 여기에 있는 파일들은 빌드 과정에서 처리되지 않고 그대로 dist 폴더로 복사됩니다.
예를 들어, robots.txt, favicon.ico, 또는 절대 경로로 참조되는 파일들을 여기에 둡니다. 주의할 점은 public의 파일들은 /파일명 형태로 절대 경로로만 참조해야 한다는 것입니다.
세 번째로, index.html은 Vite 프로젝트의 가장 독특한 특징입니다. 다른 빌드 도구들과 달리 Vite는 index.html을 프로젝트 루트에 두고, 이 파일이 진입점 역할을 합니다.
이 HTML 파일 안에서 <script type="module" src="/src/main.tsx">처럼 여러분의 메인 JavaScript/TypeScript 파일을 불러옵니다. Vite는 이 연결을 자동으로 추적해서 필요한 모든 파일을 처리합니다.
네 번째로, 설정 파일들을 살펴봅시다. package.json은 프로젝트의 이름, 버전, 의존하는 라이브러리 목록, 실행할 수 있는 스크립트 명령어들을 담고 있습니다.
vite.config.ts는 Vite의 동작 방식을 커스터마이징할 수 있는 파일로, 플러그인을 추가하거나 빌드 옵션을 변경할 때 사용합니다. tsconfig.json은 TypeScript 컴파일러 설정으로, 어떤 문법을 허용할지, 어떻게 타입 체크를 할지 등을 정의합니다.
다섯 번째로, node_modules/ 폴더는 npm이 설치한 모든 라이브러리들이 저장되는 곳입니다. 이 폴더는 매우 크기 때문에 Git에 올리지 않고 .gitignore에 등록되어 있습니다.
다른 사람이 프로젝트를 받아서 npm install을 실행하면 package.json을 보고 동일한 라이브러리들을 자동으로 설치합니다. 여러분이 이 구조를 이해하면 새로운 컴포넌트를 만들 때 src 폴더에, 정적 이미지를 추가할 때 어디에 둘지, 새로운 라이브러리를 설치했을 때 어디를 확인할지 정확히 알 수 있습니다.
또한 프로젝트가 커져도 일관된 구조를 유지할 수 있어서 팀 협업할 때도 서로 코드를 쉽게 이해할 수 있게 됩니다.
실전 팁
💡 src 폴더 안에 components, pages, hooks, utils 같은 하위 폴더를 만들어서 파일을 분류하세요. 예를 들어 src/components/Button.tsx, src/pages/Home.tsx 처럼 정리하면 프로젝트가 커져도 찾기 쉽습니다.
💡 이미지 파일은 src/assets에 두는 것이 좋습니다. 그러면 Vite가 빌드할 때 이미지를 최적화하고, 파일명에 해시를 추가해서 브라우저 캐싱 문제를 자동으로 해결해줍니다. import logo from './assets/logo.png' 형태로 사용하세요.
💡 환경 변수는 .env 파일을 루트에 만들어서 관리하세요. Vite는 VITE_로 시작하는 환경 변수만 클라이언트 코드에 노출시킵니다. API 키 같은 민감한 정보는 절대 VITE_ 접두사를 붙이지 마세요!
💡 절대 경로 import를 사용하고 싶다면 vite.config.ts에 alias를 설정하세요. import Button from '@/components/Button' 처럼 깔끔하게 import할 수 있어서 폴더 깊이가 깊어져도 ../../../ 같은 상대 경로 지옥에서 벗어날 수 있습니다.
💡 node_modules는 용량이 크므로 정기적으로 정리하세요. 사용하지 않는 의존성은 npm uninstall 패키지명으로 제거하고, 가끔 node_modules를 삭제한 후 npm install로 깨끗하게 다시 설치하면 문제를 예방할 수 있습니다.
4. vite.config.js 기본 설정
시작하며
여러분이 Vite로 프로젝트를 만들다가 이런 필요를 느낀 적 있나요? "포트 번호를 바꾸고 싶은데...", "절대 경로로 import 하고 싶은데...", "특별한 플러그인을 추가하고 싶은데..." 같은 고민들 말이에요.
이런 커스터마이징은 실제 프로젝트에서 거의 필수적입니다. 기본 설정만으로는 팀의 개발 환경, 배포 요구사항, 특별한 기능 요구사항을 모두 만족시킬 수 없거든요.
예를 들어, 회사에서는 포트 3000을 사용하도록 정해져 있거나, 레거시 브라우저를 지원해야 하거나, 특정 CSS 프레임워크를 사용해야 할 수 있습니다. 바로 이럴 때 필요한 것이 vite.config.js 파일입니다.
이 파일 하나로 Vite의 모든 동작을 여러분의 필요에 맞게 조정할 수 있습니다. 복잡한 webpack 설정과 달리, Vite 설정은 정말 간단하고 직관적이어서 초보자도 쉽게 수정할 수 있어요.
개요
간단히 말해서, vite.config.js는 Vite의 행동을 제어하는 리모콘입니다. 마치 TV 리모콘으로 채널, 볼륨, 밝기를 조절하듯이, 이 파일로 개발 서버, 빌드 과정, 플러그인 등 모든 것을 조절할 수 있어요.
왜 설정 파일이 필요한지 궁금하시죠? Vite의 기본 설정은 대부분의 경우에 잘 작동하지만, 실제 프로젝트는 각자 고유한 요구사항을 가집니다.
예를 들어, 포트 번호 변경, 프록시 설정, 경로 별칭, 환경별 빌드 설정 등은 거의 모든 실무 프로젝트에서 필요합니다. 설정 파일 없이 이런 것들을 하려면 코드 곳곳에 하드코딩해야 하는데, 그러면 유지보수가 정말 어려워집니다.
기존 webpack 설정은 수백 줄의 복잡한 코드가 필요했다면, Vite는 대부분 10-20줄이면 충분합니다. 이는 Vite가 합리적인 기본값을 제공하고, 꼭 필요한 것만 오버라이드하면 되기 때문입니다.
vite.config.js의 핵심 설정 영역은 이렇습니다. 첫째, server 옵션으로 개발 서버의 포트, 호스트, 프록시 등을 설정합니다.
둘째, build 옵션으로 빌드 결과물의 위치, 청크 크기, 소스맵 생성 여부 등을 제어합니다. 셋째, resolve 옵션으로 경로 별칭을 설정해서 import를 간편하게 만듭니다.
넷째, plugins 배열로 다양한 플러그인을 추가해서 Vite의 기능을 확장합니다. 이 네 가지만 알아도 대부분의 실무 요구사항을 해결할 수 있습니다.
코드 예제
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'
// Vite 설정 파일 - 개발 환경과 빌드를 커스터마이징
export default defineConfig({
// React 플러그인 사용 - JSX 변환과 Fast Refresh 지원
plugins: [react()],
// 개발 서버 설정
server: {
port: 3000, // 개발 서버 포트를 3000으로 변경
open: true, // 서버 시작 시 자동으로 브라우저 열기
cors: true, // CORS 활성화
proxy: { // API 프록시 설정
'/api': {
target: 'http://localhost:8080', // API 서버 주소
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
},
// 경로 별칭 설정 - import를 간편하게
resolve: {
alias: {
'@': path.resolve(__dirname, './src'), // @ = src 폴더
'@components': path.resolve(__dirname, './src/components'),
'@utils': path.resolve(__dirname, './src/utils')
}
},
// 빌드 설정
build: {
outDir: 'dist', // 빌드 결과물 폴더
sourcemap: true, // 소스맵 생성 (디버깅용)
minify: 'terser', // 코드 압축 방식
chunkSizeWarningLimit: 1000, // 청크 크기 경고 임계값 (KB)
rollupOptions: {
output: {
// 청크 파일을 논리적으로 분리
manualChunks: {
vendor: ['react', 'react-dom'], // 라이브러리를 별도 청크로
}
}
}
},
// 환경 변수 설정
define: {
__APP_VERSION__: JSON.stringify('1.0.0')
}
})
설명
이것이 하는 일: 이 설정 파일은 Vite가 개발 서버를 실행하고 프로젝트를 빌드하는 방식을 정밀하게 제어합니다. 마치 자동차의 계기판에서 여러 설정을 조정하는 것처럼, 각 옵션은 특정한 동작을 변경합니다.
첫 번째로, plugins 배열에서 React 플러그인을 등록합니다. 이 플러그인은 JSX 문법을 일반 JavaScript로 변환하고, Fast Refresh(코드 수정 시 상태를 유지하면서 즉시 반영)를 활성화합니다.
Vue를 사용한다면 @vitejs/plugin-vue를, Svelte를 사용한다면 @sveltejs/vite-plugin-svelte를 여기에 추가하면 됩니다. 플러그인은 배열이므로 여러 개를 동시에 사용할 수 있습니다.
두 번째로, server 옵션은 개발 환경을 설정합니다. port: 3000은 개발 서버를 3000번 포트에서 실행하라는 의미입니다.
open: true는 서버가 시작되면 자동으로 브라우저를 열어주고, proxy 설정은 백엔드 API가 다른 서버에 있을 때 CORS 문제를 해결해줍니다. 예를 들어 프론트엔드는 localhost:3000, 백엔드는 localhost:8080에서 실행된다면, /api로 시작하는 요청을 자동으로 백엔드 서버로 전달합니다.
세 번째로, resolve.alias는 경로 별칭을 설정해서 import 문을 깔끔하게 만듭니다. '@': path.resolve(__dirname, './src')를 설정하면 import Button from '../../../components/Button' 대신 import Button from '@/components/Button'처럼 간결하게 작성할 수 있습니다.
폴더 구조가 깊어질수록 상대 경로는 관리하기 어려워지는데, 별칭을 사용하면 이 문제가 완전히 해결됩니다. 네 번째로, build 옵션은 프로덕션 빌드를 제어합니다.
outDir은 빌드 결과물이 저장될 폴더를 지정하고, sourcemap: true는 배포된 코드에서 에러가 발생했을 때 원본 코드의 어느 부분인지 추적할 수 있게 해줍니다. manualChunks는 특히 중요한데, React 같은 큰 라이브러리를 별도 파일로 분리하면 사용자가 페이지를 다시 방문할 때 캐시된 라이브러리 파일을 재사용해서 로딩 속도가 빨라집니다.
다섯 번째로, define 옵션으로 전역 상수를 정의할 수 있습니다. __APP_VERSION__처럼 정의하면 코드 어디서든 이 값을 사용할 수 있고, 빌드할 때 실제 값으로 치환됩니다.
이는 환경별로 다른 API 엔드포인트를 사용하거나, 디버그 모드를 토글할 때 유용합니다. 여러분이 이 설정들을 사용하면 팀의 개발 환경을 표준화하고, 빌드 결과물을 최적화하며, 프로젝트 구조를 깔끔하게 유지할 수 있습니다.
특히 프록시 설정은 백엔드 개발자와 협업할 때 필수적이고, 경로 별칭은 코드 리뷰할 때 다른 팀원들이 코드를 쉽게 이해할 수 있게 해줍니다.
실전 팁
💡 환경별로 다른 설정을 사용하려면 vite.config.js에서 defineConfig의 콜백 함수 형태를 사용하세요. export default defineConfig(({ command, mode }) => { ... }) 형태로 작성하면 개발/프로덕션 환경에 따라 다른 설정을 반환할 수 있습니다.
💡 path 별칭을 설정한 후에는 반드시 tsconfig.json에도 같은 별칭을 추가하세요. "paths": { "@/*": ["./src/*"] } 처럼 설정해야 TypeScript가 타입 체크와 자동완성을 제대로 제공합니다.
💡 개발할 때는 server.host: '0.0.0.0'으로 설정하면 같은 네트워크의 다른 기기(스마트폰, 태블릿 등)에서도 접속해서 테스트할 수 있습니다. 모바일 반응형을 확인할 때 정말 유용합니다.
💡 빌드 속도가 느리다면 build.minify: 'esbuild'로 변경해보세요. terser보다 훨씬 빠르지만, 압축률은 약간 낮습니다. 개발 중에는 빠른 빌드가 더 중요하므로 esbuild를 추천합니다.
💡 CSS 전처리기(Sass, Less 등)를 사용하려면 해당 패키지만 설치하면 됩니다. npm install -D sass를 실행한 후 .scss 파일을 만들면 Vite가 자동으로 처리해줍니다. 별도의 설정이 필요 없어요!
5. 개발 서버 실행 및 Hot Module Replacement 체험
시작하며
여러분이 코드를 작성하면서 이런 답답함을 느낀 적 있나요? "코드를 수정할 때마다 브라우저를 새로고침하고, 다시 로그인하고, 다시 페이지를 찾아가야 하는 게 너무 귀찮아..." 라는 생각 말이에요.
이런 반복 작업은 개발 생산성을 심각하게 떨어뜨립니다. 버튼 색상 하나를 바꾸는데도 수십 초가 걸리고, 상태를 다시 만들어야 하니까 테스트도 힘들어집니다.
예를 들어, 로그인 후 5단계를 거쳐야 보이는 페이지를 수정할 때, 매번 처음부터 다시 시작하는 것은 정말 비효율적이죠. 이런 낭비가 하루에도 수십 번 반복되면 개발자는 지치고 집중력도 떨어집니다.
바로 이럴 때 필요한 것이 Vite의 Hot Module Replacement(HMR)입니다. HMR은 여러분이 코드를 저장하는 순간, 페이지를 새로고침하지 않고도 변경사항을 즉시 화면에 반영해줍니다.
심지어 현재 상태도 그대로 유지되어서, 여러분은 멈추지 않고 계속 개발할 수 있어요.
개요
간단히 말해서, Vite 개발 서버는 여러분의 코드를 실시간으로 브라우저에 보여주는 마법 같은 도구입니다. 마치 거울처럼, 코드를 수정하면 즉시 결과를 확인할 수 있어요.
왜 Vite의 개발 서버가 특별한지 궁금하시죠? 기존 도구들은 전체 앱을 다시 번들링하느라 느렸지만, Vite는 ES 모듈을 활용해서 변경된 파일만 교체합니다.
예를 들어, 100개의 컴포넌트 중 하나만 수정했다면 그 하나만 업데이트하는 거예요. 이는 마치 책 한 권 전체를 다시 인쇄하는 대신, 수정된 페이지만 교체하는 것과 같습니다.
기존의 webpack 개발 서버는 프로젝트가 커지면 시작하는 데만 몇 분씩 걸리고 HMR도 느렸다면, Vite는 프로젝트 크기와 무관하게 1초 이내에 서버가 시작되고 HMR은 거의 즉시 일어납니다. Vite 개발 서버의 핵심 기능은 이렇습니다.
첫째, 초고속 서버 시작 - 프로젝트 크기와 무관하게 즉시 시작됩니다. 둘째, 번개같은 HMR - 파일을 저장하면 밀리초 단위로 반영됩니다.
셋째, 정확한 에러 메시지 - 에러가 발생하면 파일명과 줄 번호를 정확히 알려줍니다. 넷째, 자동 재시작 - vite.config.js나 .env 파일을 수정하면 자동으로 재시작됩니다.
이런 기능들이 여러분의 개발 경험을 완전히 새로운 수준으로 끌어올립니다.
코드 예제
# 개발 서버 실행 - 기본 명령어
npm run dev
# 또는 특정 포트로 실행
npm run dev -- --port 3000
# 또는 모든 네트워크 인터페이스에서 접근 가능하게
npm run dev -- --host
# 서버가 시작되면 다음과 같은 출력을 볼 수 있습니다:
# VITE v5.0.0 ready in 500 ms
# ➜ Local: http://localhost:5173/
# ➜ Network: http://192.168.0.10:5173/
# ➜ press h to show help
# 이제 src/App.tsx 파일을 열어서 텍스트를 수정해보세요
# 예: "Hello Vite" -> "Hello World"
# 저장하는 순간 브라우저에 즉시 반영됩니다!
# HMR 동작 확인하기
# 1. 브라우저 개발자 도구 콘솔을 엽니다
# 2. 파일을 수정하고 저장합니다
# 3. 콘솔에서 "[vite] hot updated: /src/App.tsx" 메시지 확인
설명
이것이 하는 일: 개발 서버는 여러분의 코드를 웹 브라우저가 이해할 수 있는 형태로 변환해서 제공하고, 파일 변경을 감지해서 자동으로 업데이트합니다. 마치 동시통역사처럼, 여러분이 작성하는 TypeScript, JSX, CSS를 브라우저가 이해할 수 있는 언어로 실시간 번역해주는 거예요.
첫 번째로, npm run dev 명령어를 실행하면 Vite가 개발 서버를 시작합니다. 이 과정은 정말 빠릅니다.
프로젝트에 수백 개의 파일이 있어도 1-2초면 충분해요. 왜냐하면 Vite는 처음에 모든 파일을 번들링하지 않고, 브라우저가 요청하는 파일만 필요할 때 처리하기 때문입니다.
이를 "on-demand" 방식이라고 합니다. 두 번째로, 서버가 시작되면 터미널에 접속 URL이 표시됩니다.
Local은 여러분의 컴퓨터에서만 접속 가능한 주소이고, Network는 같은 Wi-Fi에 연결된 다른 기기에서도 접속할 수 있는 주소입니다. 스마트폰으로 Network 주소에 접속하면 모바일에서 실시간으로 변경사항을 확인할 수 있어서 반응형 디자인을 테스트할 때 정말 편리합니다.
세 번째로, HMR이 어떻게 작동하는지 살펴봅시다. 여러분이 src/App.tsx 파일의 텍스트를 수정하고 Ctrl+S(또는 Cmd+S)를 누르면, Vite는 즉시 변경을 감지합니다.
그러면 변경된 모듈만 브라우저로 전송하고, 브라우저는 해당 모듈만 교체합니다. 이 전체 과정이 100ms 이내에 일어나서, 여러분은 마치 라이브 편집을 하는 것처럼 느껴집니다.
네 번째로, HMR의 가장 큰 장점은 상태 유지입니다. 예를 들어, 여러분이 폼에 데이터를 입력하고 있는 상태에서 버튼 스타일을 수정한다면, 기존 방식은 페이지가 새로고침되면서 입력한 데이터가 사라집니다.
하지만 Vite의 HMR은 입력한 데이터를 그대로 유지한 채 버튼 스타일만 업데이트합니다. 이는 개발 속도를 몇 배나 향상시킵니다.
다섯 번째로, 에러 처리도 훌륭합니다. 코드에 문법 오류가 있으면 Vite는 브라우저 화면에 읽기 쉬운 형태로 에러를 표시합니다.
어느 파일의 몇 번째 줄에서 에러가 발생했는지, 무엇이 문제인지 정확히 알려주고, 에러를 수정하면 자동으로 화면이 복구됩니다. 콘솔을 계속 확인할 필요가 없어요.
여러분이 Vite 개발 서버를 사용하면 개발 중 기다리는 시간이 거의 사라집니다. 코드를 작성하고, 저장하고, 즉시 결과를 보는 이 빠른 피드백 루프가 창의성을 높이고, 버그를 빨리 발견하게 하며, 개발을 훨씬 즐겁게 만들어줍니다.
많은 개발자들이 Vite를 한번 사용하면 다시 예전 도구로 돌아가기 힘들다고 말하는 이유입니다.
실전 팁
💡 개발 서버가 실행 중일 때 터미널에서 'h'를 누르면 단축키 목록을 볼 수 있습니다. 'r'은 서버 재시작, 'u'는 URL 다시 표시, 'o'는 브라우저 열기, 'c'는 콘솔 지우기 등 유용한 기능들이 많아요.
💡 CSS 변경은 HMR이 완벽하게 작동하지만, 가끔 JavaScript 로직 변경은 전체 페이지 새로고침이 필요할 수 있습니다. 이런 경우를 대비해 개발자 도구의 "Preserve log" 옵션을 켜두면 새로고침 후에도 콘솔 로그를 확인할 수 있습니다.
💡 여러 프로젝트를 동시에 실행할 때는 각각 다른 포트를 사용하세요. vite.config.js에서 server.port를 설정하거나, npm run dev -- --port 3001 처럼 실행하면 됩니다. 보통 3000-3010 범위를 사용하면 충돌이 없습니다.
💡 HMR이 제대로 작동하지 않는다면 파일명과 import 경로를 확인하세요. 대소문자가 다르거나 경로가 잘못되면 HMR이 깨질 수 있습니다. 특히 Windows에서 개발하고 Linux 서버에 배포하는 경우 대소문자 문제가 자주 발생합니다.
💡 개발 서버를 HTTPS로 실행하려면 vite.config.js에서 server.https: true를 설정하세요. Vite가 자동으로 자체 서명 인증서를 생성합니다. PWA나 웹 API(카메라, 위치 등)를 테스트할 때 HTTPS가 필요한 경우가 많습니다.
6. package.json 스크립트 구성
시작하며
여러분이 프로젝트를 진행하면서 이런 불편함을 느낀 적 있나요? "매번 긴 명령어를 타이핑하는 게 귀찮아...", "빌드하고, 테스트하고, 배포하는 과정을 자동화하고 싶어..." 같은 생각 말이에요.
이런 반복 작업은 실수를 유발하고 시간을 낭비합니다. 예를 들어, 프로덕션 빌드를 할 때 환경 변수를 설정하고, 특정 옵션을 추가하고, 여러 명령어를 순서대로 실행해야 한다면, 매번 이걸 정확히 기억해서 입력하기는 정말 어렵습니다.
팀원마다 다른 명령어를 사용하면 일관성도 떨어지고, 신입 개발자는 무엇을 실행해야 할지조차 모를 수 있습니다. 바로 이럴 때 필요한 것이 package.json의 scripts 섹션입니다.
여기에 자주 사용하는 명령어들을 짧은 이름으로 등록해두면, npm run dev 같은 간단한 명령어로 복잡한 작업을 실행할 수 있습니다. 이는 마치 스마트폰의 단축키를 설정하는 것과 같아요.
개요
간단히 말해서, package.json의 scripts는 여러분이 자주 사용하는 명령어들을 저장해두는 단축키 모음입니다. 마치 전화번호를 연락처에 저장해두면 긴 번호를 외울 필요 없이 이름만 누르면 되는 것처럼, 복잡한 명령어를 짧은 이름으로 실행할 수 있어요.
왜 스크립트 구성이 중요한지 궁금하시죠? 프로젝트가 성장하면 개발, 테스트, 빌드, 배포 등 다양한 작업이 필요합니다.
각 작업마다 여러 옵션과 환경 변수가 필요한데, 이를 매번 손으로 입력하면 오타가 나거나 옵션을 빠뜨릴 수 있습니다. 예를 들어, 스테이징 환경용 빌드와 프로덕션 빌드는 다른 환경 변수를 사용해야 하는데, 스크립트로 정의해두면 실수 없이 정확하게 실행할 수 있습니다.
기존에는 Makefile이나 Gulp 같은 별도 도구로 빌드 스크립트를 관리했다면, 이제는 package.json 하나에서 모든 것을 관리합니다. npm/pnpm/yarn 모두 동일한 방식으로 작동하므로 배우기도 쉽고 사용하기도 간편합니다.
package.json scripts의 핵심 활용법은 이렇습니다. 첫째, dev, build, preview 같은 기본 스크립트로 개발 라이프사이클을 관리합니다.
둘째, test, lint, format 같은 품질 관리 스크립트로 코드 품질을 유지합니다. 셋째, pre와 post 접두사로 스크립트 실행 전후에 자동으로 실행될 작업을 정의합니다.
넷째, 환경 변수와 크로스 플랫폼 명령어를 사용해서 Windows, Mac, Linux 모두에서 동작하도록 만듭니다. 이 네 가지를 잘 활용하면 프로젝트 자동화를 완성할 수 있습니다.
코드 예제
{
"name": "my-vite-app",
"version": "1.0.0",
"type": "module",
"scripts": {
// 개발 서버 실행 - 가장 자주 사용
"dev": "vite",
// 프로덕션 빌드 - 배포용 파일 생성
"build": "tsc && vite build",
// 빌드 결과물 미리보기 - 배포 전 확인용
"preview": "vite preview",
// TypeScript 타입 체크만 실행
"type-check": "tsc --noEmit",
// ESLint로 코드 검사
"lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
// ESLint 자동 수정
"lint:fix": "eslint . --ext ts,tsx --fix",
// Prettier로 코드 포맷팅
"format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
// 테스트 실행 (Vitest 사용 시)
"test": "vitest",
"test:ui": "vitest --ui",
"test:coverage": "vitest --coverage",
// 빌드 전에 자동으로 타입 체크와 린트 실행
"prebuild": "npm run type-check && npm run lint",
// 여러 명령어를 동시에 실행 (concurrently 패키지 필요)
"dev:full": "concurrently \"npm run dev\" \"npm run test:watch\"",
// 빌드 결과물 삭제
"clean": "rimraf dist",
// 완전히 깨끗한 상태에서 빌드
"build:clean": "npm run clean && npm run build"
},
"dependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0"
},
"devDependencies": {
"@types/react": "^18.2.0",
"@types/react-dom": "^18.2.0",
"@vitejs/plugin-react": "^4.2.0",
"vite": "^5.0.0",
"typescript": "^5.3.0",
"eslint": "^8.56.0",
"prettier": "^3.1.0"
}
}
설명
이것이 하는 일: scripts 섹션은 프로젝트에서 실행할 수 있는 명령어들을 정의합니다. 각 스크립트는 이름(키)과 실제 실행할 명령어(값)의 쌍으로 구성되며, npm run [스크립트명] 형태로 실행합니다.
마치 매크로를 만들어두는 것처럼, 복잡한 명령어를 간단한 이름으로 호출할 수 있게 해줍니다. 첫 번째로, 기본 개발 스크립트들을 살펴봅시다.
"dev": "vite"는 개발 서버를 실행하는 가장 기본적인 명령어입니다. "build": "tsc && vite build"는 TypeScript 컴파일을 먼저 수행하고(tsc) 그 다음 Vite 빌드를 실행합니다.
&& 연산자는 왼쪽 명령어가 성공해야만 오른쪽을 실행한다는 의미예요. 만약 타입 에러가 있으면 빌드가 중단되어 문제가 있는 코드가 배포되는 것을 방지합니다.
두 번째로, 코드 품질 관리 스크립트입니다. `"lint": "eslint .
--ext ts,tsx"는 프로젝트 전체에서 TypeScript/TSX 파일을 검사해서 코딩 컨벤션을 확인합니다. "lint:fix"는 자동으로 고칠 수 있는 문제들을 수정해주고, "format": "prettier --write"`는 코드 스타일을 일관되게 정리합니다.
팀 프로젝트에서는 이런 스크립트를 Git 커밋 전에 자동 실행하도록 설정하면 코드 리뷰가 훨씬 수월해집니다. 세 번째로, prebuild 같은 특별한 스크립트를 주목하세요.
npm은 pre 접두사가 붙은 스크립트를 자동으로 인식합니다. npm run build를 실행하면 npm이 먼저 prebuild를 실행하고, 성공하면 build를 실행합니다.
마찬가지로 postbuild를 정의하면 빌드 후에 자동 실행됩니다. 이를 활용하면 빌드 전 검증, 빌드 후 파일 복사 등을 자동화할 수 있어요.
네 번째로, 테스트 관련 스크립트입니다. "test": "vitest"는 테스트를 한 번 실행하고, "test:ui"는 브라우저에서 시각적으로 테스트 결과를 보여주며, "test:coverage"는 코드 커버리지 리포트를 생성합니다.
콜론(:)은 npm의 관례로, 관련된 스크립트들을 그룹화할 때 사용합니다. 예를 들어 build:dev, build:prod, build:staging 처럼 환경별 빌드 스크립트를 만들 수 있습니다.
다섯 번째로, 유틸리티 스크립트도 유용합니다. "clean": "rimraf dist"는 빌드 폴더를 삭제합니다.
rimraf는 크로스 플랫폼 삭제 도구로, Windows의 rmdir과 Unix의 rm -rf를 통합한 것입니다. "build:clean"은 깨끗한 빌드를 보장하기 위해 먼저 기존 파일을 삭제하고 빌드합니다.
가끔 캐시 문제로 이상한 버그가 생길 때 이 스크립트를 실행하면 해결되는 경우가 많아요. 여러분이 이런 스크립트들을 잘 구성하면 프로젝트의 모든 작업을 표준화할 수 있습니다.
새로운 팀원이 합류해도 npm run dev로 개발을 시작하고, npm run build로 빌드하고, npm run test로 테스트한다는 것을 즉시 알 수 있어요. 또한 CI/CD 파이프라인에서도 이 스크립트들을 그대로 사용할 수 있어서 로컬 환경과 배포 환경의 일관성이 보장됩니다.
실전 팁
💡 환경 변수를 스크립트에서 사용하려면 cross-env 패키지를 설치하세요. "build:prod": "cross-env NODE_ENV=production vite build" 처럼 사용하면 Windows, Mac, Linux 모두에서 동작합니다. 환경 변수 설정 문법이 OS마다 다른 문제를 해결해줍니다.
💡 스크립트를 실행할 때 추가 인자를 전달하려면 --를 사용하세요. 예를 들어 npm run dev -- --port 3000은 dev 스크립트에 --port 3000을 전달합니다. 이 방법으로 스크립트를 유연하게 사용할 수 있어요.
💡 여러 명령어를 동시에 실행하려면 concurrently 패키지를 사용하세요. "dev:all": "concurrently \"npm run dev\" \"npm run server\" \"npm run watch:css\"" 처럼 작성하면 프론트엔드, 백엔드, CSS 빌드를 동시에 실행할 수 있습니다.
💡 스크립트가 너무 길어지면 별도의 쉘 스크립트 파일로 분리하세요. "deploy": "bash scripts/deploy.sh" 처럼 작성하고, 복잡한 로직은 scripts 폴더의 파일에 작성하면 가독성이 좋아집니다.
💡 Git hooks와 연동하려면 husky를 사용하세요. 커밋 전에 자동으로 린트와 테스트를 실행하도록 설정하면 나쁜 코드가 저장소에 들어가는 것을 방지할 수 있습니다. npx husky-init으로 쉽게 설정할 수 있어요.