Vite + Vue 3 프로젝트 설계 가이드

Vite는 빠른 dev server와 간단한 설정 덕분에 Vue 3 프로젝트의 기본 선택지에 가깝습니다. 하지만 실무에서는 단순히 프로젝트를 생성하는 것보다, 개발 환경과 배포 환경을 어떻게 나눌지, alias와 환경 변수를 어떤 규칙으로 관리할지, 빌드 결과를 어떻게 안정적으로 운영할지가 더 중요합니다.

빠른 시작보다 중요한 기준

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

이 단계는 쉬우나, 실제 품질은 그 다음 설정에서 갈립니다. 폴더 구조가 커졌을 때 import 경로가 난잡해지지 않는지, 환경별 API 주소가 안전하게 분리되는지, 프록시가 로컬 개발 경험을 단순하게 만드는지가 핵심입니다.

alias와 환경 변수는 초기에 규칙을 정한다

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

alias는 단순 편의 기능이 아니라 구조를 읽기 쉽게 만드는 장치입니다. 환경 변수는 VITE_ 접두 규칙을 명확히 지키고, 서버 전용 비밀값이 프런트 번들에 섞이지 않도록 주의해야 합니다.

개발 서버와 운영 번들을 구분해서 생각한다

Vite dev server가 빠르다고 해서 운영 최적화까지 자동으로 해결되는 것은 아닙니다. chunk 분리, asset 크기, 캐시 전략, CDN 배치, sourcemap 노출 범위는 운영 기준으로 별도 점검해야 합니다.

Vue 3 프로젝트에서 Vite가 주는 장점

Composition API, <script setup>, TypeScript, HMR이 자연스럽게 맞물린다는 점이 가장 큽니다. 특히 컴포넌트 수정 시 피드백이 빠르기 때문에 UI 개발 속도가 올라갑니다. 다만 속도가 빠르다는 이유로 구조적 문제를 미루면 프로젝트가 커질수록 이점이 줄어듭니다.

자주 하는 실수

환경 변수를 무분별하게 늘리거나, 프록시와 실제 운영 API 경로를 다르게 가져가 로컬과 운영 동작이 어긋나는 경우가 많습니다. 또 빌드가 빠르다는 이유로 번들 크기나 third-party 의존성 증가를 방치하는 것도 흔한 문제입니다.

마무리

Vite + Vue 3 조합은 빠르고 가볍지만, 실무에서는 개발 경험과 운영 안정성을 함께 설계해야 합니다. alias, proxy, env, build 전략을 초기에 정리해 두면 프로젝트가 커져도 속도 이점을 오래 유지할 수 있습니다.

운영 환경에서 어려워지는 지점

로컬 시작 속도가 빠르다고 해서 alias, 환경 변수, 테스트, 빌드 대상이 갈라진 뒤에도 유지보수가 쉬운 것은 아니다.
디렉터리 구조와 플러그인 기준을 초기에 문서화하지 않으면 팀은 금방 초기 셋업을 넘어선다.
Vite 설정을 일회성 보일러플레이트로 보면 자산 파이프라인과 환경 처리부터 흔들리기 쉽다.

중요한 아키텍처 결정

Vite 설정은 작게 유지하되 alias, env 이름 규칙, 플러그인 정책은 초기에 정한다.
앱 부트스트랩, 라우터 부트스트랩, 공용 런타임 설정을 분리해 초기화 흐름을 읽기 쉽게 만든다.
테스트 셋업, 모킹 전략, 빌드 모드 동작을 나중 정리가 아니라 아키텍처 일부로 다룬다.

실무 예시

깔끔한 셋업은 실제로 필요한 런타임 설정만 앱에 노출한다.

export function readRuntimeConfig() {
  return {
    apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
    appEnv: import.meta.env.MODE,
    enableMockApi: import.meta.env.VITE_ENABLE_MOCK_API === 'true',
  }
}

피해야 할 안티패턴

각 기능이 import.meta.env를 직접 읽게 두는 것.
빌드 영향과 역할 중복을 보지 않고 플러그인을 계속 쌓는 것.
앱 초기화 코드와 전역 부작용, 디버그 전용 동작을 섞는 것.

운영 체크리스트

필수 환경 변수와 기본값을 문서화한다.
CI와 배포에서 쓰는 각 모드별 번들 결과를 확인한다.
dev 서버 proxy 규칙을 백엔드 계약 변경과 함께 관리한다.
각 Vite 플러그인이 지금도 복잡도를 감당할 가치가 있는지 검토한다.

최종 판단

Vite와 Vue 3의 강점은 의도적으로 작은 셋업을 유지할 때 더 커진다. 초기 속도는 출발점이고, 런타임 설정과 빌드 동작의 일관성이 장기 건강성을 만든다.

다음으로 읽기 좋은 글

🖥️ Frontend

AI 서비스 개발, 운영, 성능개선을 하나의 루프로 연결합니다