[Vue] Installation

공식 문서: Vue - Quick Start, Vite - Getting Started

Vue 설치 방식

Vue project를 시작하는 공식적인 기본 방법은 create-vue를 사용하는 것이다.

npm create vue@latest

이 명령어는 Vue 공식 scaffolding tool인 create-vue를 실행한다. 생성되는 project는 Vite 기반이며, Vue Single-File Component를 사용할 수 있다.

이 글에서는 npm 기준으로 Vue project를 생성하고 실행하는 방법을 정리한다.

사전 준비

먼저 Node.js와 npm이 설치되어 있어야 한다.

node --version
npm --version

Vue 공식 문서 기준으로 Node.js ^20.19.0 || >=22.12.0 버전이 필요하다. 버전이 낮다면 Node.js를 업데이트해야 한다.

Vue project 생성

다음 명령어를 실행한다.

npm create vue@latest

명령어를 실행하면 여러 선택지가 나온다.

Project name: my-vue-app
Add TypeScript? No / Yes
Add JSX Support? No / Yes
Add Vue Router? No / Yes
Add Pinia? No / Yes
Add Vitest? No / Yes
Add an End-to-End Testing Solution? No / Cypress / Nightwatch / Playwright
Add ESLint? No / Yes
Add Prettier? No / Yes

처음 학습하는 단계라면 대부분 No를 선택해도 된다. 실제 project라면 TypeScript, Vue Router, Pinia, ESLint, Prettier를 함께 선택하는 경우가 많다.

선택지 기준

각 선택지는 다음 의미를 가진다.

처음에는 다음 조합이 무난하다.

TypeScript: Yes
Vue Router: project에 page가 여러 개면 Yes
Pinia: 전역 상태가 필요하면 Yes
ESLint: Yes
Prettier: Yes

의존성 설치

project directory로 이동한다.

cd my-vue-app

의존성을 설치한다.

npm install

개발 서버 실행

개발 서버를 실행한다.

npm run dev

Vite 기반 project이므로 보통 다음 주소로 열린다.

http://localhost:5173

terminal에 표시되는 local URL을 browser에서 열면 Vue app을 확인할 수 있다.

생성된 project 구조

Vue project의 기본 구조는 선택한 option에 따라 조금 달라진다. 대략적인 구조는 다음과 같다.

my-vue-app/
  index.html
  package.json
  vite.config.ts
  src/
    main.ts
    App.vue
    assets/
    components/

주요 파일은 다음과 같다.

main.ts

Vue entry file은 보통 다음 형태이다.

import './assets/main.css'

import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

핵심은 createApp(App).mount('#app')이다. index.html의 app element에 Vue application을 mount한다.

<div id="app"></div>

App.vue

Vue의 Single-File Component는 template, script, style을 한 파일에 작성할 수 있다.

<script setup lang="ts">
const message = 'Hello Vue'
</script>

<template>
  <main>
    <h1>{{ message }}</h1>
    <p>Vue app is running.</p>
  </main>
</template>

<style scoped>
h1 {
  color: #42b883;
}
</style>

각 block의 역할은 다음과 같다.

Vue 공식 template은 Composition API와 <script setup>을 사용한다.

npm script

package.json에는 보통 다음 script가 들어 있다.

{
  "scripts": {
    "dev": "vite",
    "build": "run-p type-check \"build-only {@}\" --",
    "preview": "vite preview",
    "lint": "eslint . --fix",
    "format": "prettier --write src/"
  }
}

선택한 option에 따라 script는 달라질 수 있다.

기본적으로 자주 쓰는 명령어는 다음과 같다.

production build

배포용 파일을 만들려면 다음 명령어를 실행한다.

npm run build

성공하면 dist directory가 생성된다.

dist/
  index.html
  assets/

이 directory를 정적 hosting 서비스에 배포하면 된다.

local에서 build 결과를 확인하려면 다음 명령어를 사용한다.

npm run preview

Vite template으로 바로 만들기

Vue 공식 quick start는 npm create vue@latest를 권장한다. 하지만 Vite template을 직접 지정해서 만들 수도 있다.

npm create vite@latest my-vue-app -- --template vue

TypeScript template은 다음과 같다.

npm create vite@latest my-vue-app -- --template vue-ts

차이는 다음과 같다.

일반적인 Vue app은 npm create vue@latest로 시작하는 것이 좋다.

자주 생기는 문제

Node.js version 문제

설치 중 Node.js version 관련 warning이 나오면 버전을 확인한다.

node --version

Vue/Vite가 요구하는 Node.js version을 만족하도록 업데이트한다.

port가 이미 사용 중인 경우

기본 port가 사용 중이면 Vite가 다른 port를 사용한다. 직접 지정할 수도 있다.

npm run dev -- --port 3000

package 설치 문제

dependency 설치가 꼬였을 때는 node_modules를 지우고 다시 설치할 수 있다.

rm -rf node_modules package-lock.json
npm install

팀 project에서는 lock file 삭제가 dependency version을 바꿀 수 있으므로 주의해야 한다.

정리

Vue project 설치 흐름은 다음과 같다.

npm create vue@latest
cd my-vue-app
npm install
npm run dev

핵심은 다음과 같다.

1. Node.js와 npm을 먼저 준비한다.
2. Vue 공식 scaffolding tool은 create-vue이다.
3. npm create vue@latest로 project를 생성한다.
4. 필요한 경우 TypeScript, Vue Router, Pinia, ESLint, Prettier를 선택한다.
5. npm install로 dependency를 설치한다.
6. npm run dev로 개발 서버를 실행한다.
7. 배포 전에는 npm run build를 실행한다.

처음 학습할 때는 option을 최소화해도 된다. 실제 application을 만들 때는 TypeScript, Vue Router, Pinia, ESLint, Prettier를 함께 고려하는 것이 좋다.