Webpack에서 Vite로 마이그레이션 완벽 가이드

레거시 Webpack 프로젝트를 최신 Vite로 안전하게 전환하는 방법을 단계별로 소개합니다. 마이그레이션 체크리스트부터 성능 비교까지, 실무에서 바로 적용할 수 있는 완벽한 가이드입니다.

---

목차

1. 마이그레이션_체크리스트
2. webpack.config.js_에서_vite.config.js_변환
3. Webpack_플러그인_대체_방법
4. CommonJS_에서_ESM_모듈_전환
5. 빌드_스크립트_수정사항
6. 마이그레이션_후_성능_비교_및_트러블슈팅

---

1. 마이그레이션_체크리스트

시작하며

여러분이 오래된 Webpack 프로젝트를 운영하면서 빌드 시간이 점점 느려지고, 개발 서버가 시작하는데 몇 분씩 걸리는 상황을 겪어본 적 있나요? 특히 팀원이 늘어나고 코드가 많아질수록 이런 문제는 더 심각해집니다.

이런 문제는 실제 개발 현장에서 개발 생산성을 크게 떨어뜨립니다. Webpack은 훌륭한 도구이지만, 전체 번들링 방식이라는 근본적인 특성 때문에 프로젝트가 커질수록 느려질 수밖에 없습니다.

개발자들은 코드 한 줄 수정하고 결과를 보기 위해 수십 초를 기다려야 하죠. 바로 이럴 때 필요한 것이 체계적인 Vite 마이그레이션입니다.

Vite는 ESM 기반의 개발 서버와 Rollup 기반의 최적화된 빌드를 제공하여, 개발 서버는 즉시 시작되고 HMR(Hot Module Replacement)은 번개처럼 빠릅니다.

개요

간단히 말해서, 마이그레이션 체크리스트는 Webpack 프로젝트를 Vite로 안전하게 전환하기 위해 확인해야 할 필수 항목들의 목록입니다. 마이그레이션을 시작하기 전에 프로젝트의 현재 상태를 정확히 파악하는 것이 매우 중요합니다.

예를 들어, 프로젝트에서 사용 중인 Webpack 플러그인 목록, CommonJS/ESM 모듈 형식, 환경변수 사용 방식, 정적 파일 처리 방법 등을 미리 체크해야 합니다. 이런 준비 없이 무작정 시작하면 중간에 예상치 못한 문제를 만나게 됩니다.

기존에는 문제가 생길 때마다 하나씩 해결하며 진행했다면, 이제는 체크리스트를 통해 미리 모든 이슈를 파악하고 계획적으로 진행할 수 있습니다. 체크리스트의 핵심 특징은 프로젝트 의존성 분석, Webpack 설정 파악, 브라우저 호환성 확인입니다.

이러한 특징들이 마이그레이션 실패 위험을 크게 줄여주고, 예상 작업 시간을 정확히 산정할 수 있게 해줍니다.

코드 예제

// 마이그레이션 전 체크리스트 스크립트
const fs = require('fs');
const path = require('path');

// package.json 분석
const pkg = require('./package.json');
console.log('📦 Dependencies 체크:');
console.log('- Webpack 버전:', pkg.devDependencies.webpack);
console.log('- Webpack 플러그인:', Object.keys(pkg.devDependencies).filter(d => d.includes('webpack')));

// CommonJS 사용 여부 체크
console.log('\n📝 모듈 형식 체크:');
console.log('- type 필드:', pkg.type || 'commonjs (기본값)');

// 정적 파일 위치 확인
const publicDir = fs.existsSync('./public') ? './public' : './static';
console.log('\n📁 정적 파일 디렉토리:', publicDir);

// 환경변수 파일 확인
const hasEnv = fs.existsSync('.env');
console.log('- .env 파일:', hasEnv ? '존재' : '없음');

설명

이것이 하는 일: 이 체크리스트 스크립트는 현재 프로젝트의 Webpack 관련 설정과 구조를 자동으로 분석하여, Vite로 마이그레이션하기 전에 확인해야 할 사항들을 리포트로 출력합니다. 첫 번째로, package.json 파일을 분석하여 현재 설치된 Webpack 버전과 모든 Webpack 관련 플러그인을 찾아냅니다.

이렇게 하는 이유는 각 플러그인마다 Vite에서 대체할 방법이 다르기 때문입니다. 예를 들어 html-webpack-plugin은 Vite에 내장되어 있지만, copy-webpack-plugin은 설정 방식이 다릅니다.

그 다음으로, 프로젝트가 CommonJS를 사용하는지 ESM을 사용하는지 확인합니다. package.json의 type 필드가 없으면 기본적으로 CommonJS 모드이며, 이 경우 모든 import/export 문을 ESM으로 전환해야 합니다.

또한 정적 파일이 어디에 위치하는지 확인합니다. Webpack은 보통 public 또는 static 디렉토리를 사용하는데, Vite는 기본적으로 public 디렉토리만 인식합니다.

마지막으로, 환경변수 파일의 존재 여부를 체크합니다. Webpack은 process.env.VARIABLE_NAME 형식을 사용하지만, Vite는 import.meta.env.VITE_VARIABLE_NAME 형식을 사용하므로, 모든 환경변수 참조를 수정해야 합니다.

여러분이 이 체크리스트를 사용하면 마이그레이션 전체 범위를 명확히 파악할 수 있고, 각 단계별 작업량을 예측할 수 있으며, 예상치 못한 문제를 미리 발견할 수 있습니다.

실전 팁

💡 마이그레이션을 시작하기 전에 반드시 새로운 브랜치를 만들고, 모든 테스트가 통과하는지 확인하세요. 문제가 생겼을 때 쉽게 되돌릴 수 있습니다.

💡 프로젝트가 크다면 한 번에 전체를 마이그레이션하지 말고, 특정 모듈이나 페이지부터 단계적으로 진행하세요. 점진적 마이그레이션이 위험을 줄입니다.

💡 webpack-bundle-analyzer를 사용해서 현재 번들 크기와 구조를 먼저 분석하고, 마이그레이션 후 rollup-plugin-visualizer로 비교하세요.

💡 TypeScript 프로젝트라면 tsconfig.json의 module 옵션이 "ESNext" 또는 "ES2020"인지 확인하세요. CommonJS 모듈 해석 방식은 Vite와 호환되지 않습니다.

💡 Node.js 버전을 확인하세요. Vite는 최소 Node.js 14.18+ 버전이 필요하며, 18+ 버전을 권장합니다.

---

2. webpack.config.js_에서_vite.config.js_변환

시작하며

여러분이 복잡한 webpack.config.js 파일을 보면서 "이걸 어떻게 Vite로 옮기지?"라고 막막함을 느낀 적 있나요? 수백 줄의 설정과 수많은 플러그인들이 뒤섞여 있는 Webpack 설정은 이해하기도 어렵고, 유지보수도 힘듭니다.

이런 복잡한 설정은 프로젝트에 새로 합류한 개발자들에게 큰 진입 장벽이 됩니다. 또한 Webpack 버전이 올라가면서 설정 방식이 바뀔 때마다 마이그레이션 작업이 필요하고, 각종 로더와 플러그인 간의 호환성 문제도 자주 발생합니다.

바로 이럴 때 필요한 것이 Vite의 간결한 설정 방식입니다. Vite는 "제로 설정(Zero Config)" 철학을 따르면서도, 필요한 경우 간단하게 커스터마이징할 수 있는 유연한 구조를 제공합니다.

개요

간단히 말해서, webpack.config.js에서 vite.config.js로의 변환은 복잡한 Webpack 설정을 Vite의 간결하고 직관적인 설정으로 옮기는 과정입니다. Vite는 대부분의 일반적인 사용 사례에 대해 합리적인 기본값을 제공하기 때문에, Webpack에서 명시적으로 설정해야 했던 많은 부분들이 자동으로 처리됩니다.

예를 들어, Webpack에서는 babel-loader, css-loader, file-loader 등 수많은 로더를 설정해야 했지만, Vite는 이런 것들을 기본적으로 지원합니다. CSS, TypeScript, JSX, 이미지 파일 등이 별도 설정 없이 바로 동작합니다.

기존에는 entry, output, module.rules, plugins 등 여러 섹션에 걸쳐 설정을 나눠야 했다면, 이제는 훨씬 단순한 구조로 같은 기능을 구현할 수 있습니다. Vite 설정의 핵심 특징은 플러그인 기반 아키텍처, Rollup 호환성, 개발/프로덕션 통합 설정입니다.

이러한 특징들이 설정을 더 이해하기 쉽고 유지보수하기 편하게 만들어줍니다.

코드 예제

// webpack.config.js (기존 설정)
module.exports = {
  entry: './src/main.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js'
  },
  module: {
    rules: [
      { test: /\.css$/, use: ['style-loader', 'css-loader'] },
      { test: /\.(png|jpg)$/, type: 'asset/resource' }
    ]
  }
};

// vite.config.js (변환 후 - 훨씬 간결함)
import { defineConfig } from 'vite';

export default defineConfig({
  // entry와 output은 자동 처리됨 (index.html 기반)
  build: {
    outDir: 'dist', // output.path 대체
    rollupOptions: {
      output: {
        entryFileNames: '[name].[hash].js' // filename 대체
      }
    }
  }
  // CSS와 이미지는 기본 지원으로 별도 설정 불필요
});

설명

이것이 하는 일: 이 변환 과정은 Webpack의 여러 설정 섹션들을 Vite의 통합된 설정 구조로 단순화하면서도, 동일한 빌드 결과를 얻을 수 있도록 합니다. 첫 번째로, Webpack의 entry와 output 설정을 보면 진입점과 출력 경로를 명시적으로 지정해야 합니다.

하지만 Vite는 index.html을 프로젝트의 진입점으로 사용하는 "HTML 중심" 접근 방식을 취합니다. index.html에서 <script type="module" src="/src/main.js">로 메인 스크립트를 참조하면, Vite가 자동으로 이를 인식하고 처리합니다.

이 방식이 더 직관적이고 자연스럽습니다. 그 다음으로, Webpack의 module.rules에서 정의하던 각종 로더들을 살펴보면, Vite는 이런 것들을 기본적으로 지원합니다.

CSS 파일은 자동으로 처리되어 스타일이 적용되고, 이미지나 폰트 같은 정적 자산도 import로 바로 사용할 수 있습니다. PostCSS, Sass, Less도 해당 패키지만 설치하면 즉시 동작합니다.

세 번째로, 빌드 출력 파일명 패턴을 보면 Webpack은 [contenthash]를 사용하고 Vite는 [hash]를 사용하지만, 둘 다 파일 내용 기반 해시를 생성하여 브라우저 캐싱을 효율적으로 관리합니다. Vite의 build.rollupOptions를 통해 Rollup의 모든 설정에 접근할 수 있어, 필요한 경우 세밀한 제어가 가능합니다.

마지막으로, 개발 서버 설정도 훨씬 간단해집니다. Webpack의 devServer 객체에서 설정하던 proxy, port, hot 등의 옵션들이 Vite에서는 server 객체 하나로 통합되어 관리됩니다.

여러분이 이 변환 방식을 이해하면 설정 파일의 크기를 절반 이하로 줄일 수 있고, 새로운 팀원이 프로젝트 설정을 이해하는 시간을 크게 단축시킬 수 있으며, 설정 관련 버그나 호환성 문제를 대폭 감소시킬 수 있습니다.

실전 팁

💡 Webpack의 resolve.alias 설정은 Vite의 resolve.alias에 그대로 옮길 수 있습니다. 경로 별칭은 동일한 방식으로 작동합니다.

💡 환경별 설정이 필요하면 defineConfig에서 command와 mode 파라미터를 활용하세요. 개발/프로덕션 환경에 따라 다른 설정을 반환할 수 있습니다.

💡 Webpack의 DefinePlugin은 Vite의 define 옵션으로 대체됩니다. 전역 상수를 정의할 때 사용하세요.

💡 소스맵 설정은 build.sourcemap 옵션으로 간단히 제어할 수 있습니다. 개발 시에는 true, 프로덕션에서는 'hidden'을 권장합니다.

💡 Webpack의 publicPath는 Vite의 base 옵션과 동일합니다. CDN이나 서브 경로에 배포할 때 설정하세요.

---

3. Webpack_플러그인_대체_방법

시작하며

여러분이 Webpack 프로젝트에서 html-webpack-plugin, copy-webpack-plugin, clean-webpack-plugin 등 수많은 플러그인을 사용하고 있다면, 이것들을 Vite에서 어떻게 대체할지 고민이 되실 겁니다. 각 플러그인마다 다른 방식으로 설정되어 있고, 상호 의존성도 있어서 하나씩 바꾸기가 쉽지 않습니다.

이런 플러그인 의존성 문제는 마이그레이션에서 가장 큰 걸림돌입니다. 특정 플러그인이 Vite에 없다면 프로젝트 전체를 재구성해야 할 수도 있고, 플러그인 간의 실행 순서나 옵션 차이 때문에 예상치 못한 버그가 발생할 수도 있습니다.

바로 이럴 때 필요한 것이 Webpack 플러그인과 Vite 플러그인/기능 간의 명확한 매핑 테이블입니다. 대부분의 Webpack 플러그인은 Vite의 내장 기능이거나 공식 플러그인으로 대체 가능합니다.

개요

간단히 말해서, Webpack 플러그인 대체는 기존 프로젝트에서 사용하던 Webpack 플러그인들을 Vite의 내장 기능이나 호환 플러그인으로 변경하는 작업입니다. Vite는 많은 기능을 기본으로 제공하기 때문에 실제로 별도 플러그인이 필요한 경우가 많지 않습니다.

예를 들어, HTML 템플릿 처리, 정적 파일 복사, 빌드 디렉토리 정리 등은 모두 Vite에 내장되어 있습니다. 또한 Vite의 플러그인 시스템은 Rollup 플러그인과 호환되므로, Rollup 생태계의 수천 개 플러그인을 그대로 사용할 수 있습니다.

기존에는 각 기능마다 별도의 Webpack 플러그인을 찾아서 설치하고 설정해야 했다면, 이제는 대부분 기본 제공되거나 간단한 옵션 설정만으로 해결됩니다. 플러그인 대체의 핵심 원칙은 내장 기능 우선 사용, Rollup 플러그인 호환성 활용, 필요시 Vite 전용 플러그인 사용입니다.

이러한 원칙을 따르면 의존성을 최소화하고 유지보수를 쉽게 할 수 있습니다.

코드 예제

// Webpack 플러그인 설정 (기존)
const HtmlWebpackPlugin = require('html-webpack-plugin');
const CopyWebpackPlugin = require('copy-webpack-plugin');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin(), // 빌드 전 디렉토리 정리
    new HtmlWebpackPlugin({ template: './src/index.html' }), // HTML 생성
    new CopyWebpackPlugin({ patterns: [{ from: 'public', to: 'dist' }] }) // 정적 파일 복사
  ]
};

// Vite 설정 (변환 후 - 모두 기본 지원)
import { defineConfig } from 'vite';

export default defineConfig({
  // CleanWebpackPlugin: 기본으로 빌드 전 outDir 정리됨
  // HtmlWebpackPlugin: index.html이 자동으로 처리됨
  // CopyWebpackPlugin: public 폴더가 자동으로 복사됨
  publicDir: 'public', // 정적 파일 디렉토리 (기본값)
  build: {
    outDir: 'dist',
    emptyOutDir: true // 빌드 전 디렉토리 정리 (기본값 true)
  }
});

설명

이것이 하는 일: 이 대체 과정은 Webpack에서 플러그인으로 구현하던 기능들을 Vite의 기본 동작이나 간단한 설정으로 변경하여, 복잡도를 줄이면서도 같은 결과를 얻습니다. 첫 번째로, CleanWebpackPlugin은 빌드 전에 출력 디렉토리를 깨끗하게 정리하는 역할을 합니다.

Vite는 이 기능이 기본으로 활성화되어 있어서 build.emptyOutDir 옵션이 기본적으로 true입니다. 따라서 별도 플러그인 없이 매번 빌드할 때마다 이전 파일들이 자동으로 삭제됩니다.

그 다음으로, HtmlWebpackPlugin은 Webpack 번들을 참조하는 HTML 파일을 자동으로 생성하는 강력한 플러그인입니다. Vite는 이와 다른 접근 방식을 사용하는데, 프로젝트 루트의 index.html을 진입점으로 인식하고 빌드 시 자동으로 처리합니다.

<script type="module">로 스크립트를 참조하면 Vite가 알아서 번들링하고 해시를 추가하며 최적화합니다. 템플릿 변수가 필요하면 vite-plugin-html을 사용할 수 있습니다. 세 번째로, CopyWebpackPlugin은 정적 파일을 빌드 출력 디렉토리로 복사합니다. Vite는 publicDir 옵션으로 지정한 디렉토리(기본값 'public')의 모든 내용을 빌드 시 자동으로 복사합니다. public/favicon.ico나 public/robots.txt 같은 파일들이 dist 디렉토리에 그대로 복사되죠. 추가로, MiniCssExtractPlugin(CSS 분리), CompressionWebpackPlugin(Gzip 압축), BundleAnalyzerPlugin(번들 분석) 같은 플러그인들도 대체 방법이 있습니다. CSS는 자동으로 분리되고, Gzip은 build.compress 또는 서버 설정으로 처리하며, 번들 분석은 rollup-plugin-visualizer를 사용합니다. 여러분이 이런 대체 방법을 적용하면 package.json의 devDependencies 항목을 크게 줄일 수 있고, 플러그인 버전 업데이트나 호환성 문제에서 자유로워지며, 빌드 설정을 누구나 쉽게 이해할 수 있게 됩니다. ### 실전 팁 💡 DotenvWebpackPlugin을 사용했다면 제거하세요. Vite는 .env 파일을 자동으로 로드하며, VITE_ 접두사가 붙은 변수만 클라이언트에 노출합니다. 💡 React를 사용한다면 @vitejs/plugin-react를, Vue를 사용한다면 @vitejs/plugin-vue를 설치하세요. 이것들은 공식 플러그인으로 JSX/SFC를 완벽하게 지원합니다. 💡 ESLintPlugin이나 StylelintPlugin은 Vite 플러그인으로 옮기지 말고, 별도의 npm script나 pre-commit hook으로 실행하는 것이 더 빠릅니다. 💡 레거시 브라우저 지원이 필요하면 @vitejs/plugin-legacy를 사용하세요. Babel 폴리필과 트랜스파일을 자동으로 처리합니다. 💡 Webpack의 ProvidePlugin(전역 변수 자동 주입)은 Vite의 define 옵션이나 optimizeDeps.esbuildOptions.inject로 대체할 수 있습니다. --- ## 4. CommonJS_에서_ESM_모듈_전환 ### 시작하며 여러분이 오래된 Node.js 스타일의 require()와 module.exports를 사용하는 코드베이스를 보면서, "이걸 전부 import/export로 바꿔야 하나?"라고 걱정하신 적 있나요? 수십 개의 파일에 걸쳐 있는 require 구문들을 하나하나 찾아서 바꾸는 것은 정말 지루하고 실수하기 쉬운 작업입니다. 이런 모듈 시스템 불일치는 단순히 문법 차이를 넘어서 런타임 동작 차이로 이어집니다. CommonJS는 동기적으로 모듈을 로드하고, ESM은 비동기적으로 로드하며, 이로 인해 순환 참조 처리나 사이드 이펙트 실행 시점이 달라질 수 있습니다. Vite는 네이티브 ESM을 기반으로 하기 때문에 CommonJS 코드는 제대로 동작하지 않을 수 있습니다. 바로 이럴 때 필요한 것이 체계적인 ESM 전환 전략입니다. 올바른 순서와 방법으로 진행하면 안전하게 모듈 시스템을 전환하고, 최신 JavaScript 표준을 따르는 깔끔한 코드베이스를 얻을 수 있습니다. ### 개요 간단히 말해서, CommonJS에서 ESM으로의 전환은 오래된 require/module.exports 문법을 최신 import/export 문법으로 변경하고, 모듈 로딩 방식을 동기에서 비동기로 전환하는 과정입니다. ESM(ECMAScript Modules)은 JavaScript의 공식 표준 모듈 시스템으로, 브라우저와 Node.js 모두에서 네이티브로 지원됩니다. 예를 들어, 브라우저는 <script type="module">을 통해 ESM을 직접 로드할 수 있고, 번들러 없이도 모듈 단위로 코드를 나눌 수 있습니다. Vite는 개발 중에 이 네이티브 ESM 지원을 최대한 활용하여 번개처럼 빠른 속도를 제공합니다. 기존에는 모든 모듈이 즉시 실행되고 동기적으로 로드되었다면, 이제는 정적 분석이 가능한 import 문을 사용하여 트리 쉐이킹(사용하지 않는 코드 제거)과 코드 스플리팅(코드 분할)이 자동으로 최적화됩니다. ESM 전환의 핵심 포인트는 named export vs default export 선택, 동적 import 활용, __dirname/__filename 대체입니다. 이러한 포인트들을 정확히 이해하면 전환 과정에서 발생할 수 있는 버그를 예방할 수 있습니다. ### 코드 예제 ```javascript // CommonJS (기존 코드) const fs = require('fs'); const path = require('path'); const utils = require('./utils'); function processFile(filename) { const filePath = path.join(__dirname, 'data', filename); const content = fs.readFileSync(filePath, 'utf-8'); return utils.parse(content); } module.exports = { processFile }; module.exports.default = processFile; // ESM (변환 후) import fs from 'fs'; import path from 'path'; import { parse } from './utils.js'; // 확장자 명시 권장 import { fileURLToPath } from 'url'; // __dirname 대체 (ESM에는 없음) const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); export function processFile(filename) { const filePath = path.join(__dirname, 'data', filename); const content = fs.readFileSync(filePath, 'utf-8'); return parse(content); } export default processFile; // default export도 제공 ``` ### 설명 이것이 하는 일: 이 전환 과정은 Node.js의 오래된 모듈 시스템을 현대적인 표준 모듈 시스템으로 업그레이드하여, Vite와 완벽하게 호환되도록 만듭니다. 첫 번째로, require() 구문을 import 구문으로 바꿉니다. require는 런타임에 동적으로 실행되지만, import는 파일 최상단에서 정적으로 선언되어야 합니다. 이 차이가 중요한 이유는 번들러가 정적 import를 분석하여 사용하지 않는 코드를 자동으로 제거할 수 있기 때문입니다. 또한 ESM에서는 파일 확장자를 명시하는 것이 권장되므로 './utils'를 './utils.js'로 바꿉니다. 그 다음으로, module.exports를 export 키워드로 변경합니다. CommonJS는 module.exports 객체에 원하는 값을 할당하는 방식이지만, ESM은 export 키워드를 사용하여 명시적으로 내보낼 것을 선언합니다. named export(export function)는 여러 개를 내보낼 수 있고, default export(export default)는 하나만 내보낼 수 있습니다. 혼란을 피하려면 하나의 스타일로 통일하는 것이 좋습니다. 세 번째로, CommonJS의 __dirname과 __filename 변수를 처리합니다. 이 변수들은 ESM에서 제공되지 않으므로, import.meta.url을 사용하여 직접 계산해야 합니다. import.meta.url은 현재 모듈의 URL을 반환하고, fileURLToPath()로 파일 시스템 경로로 변환합니다. 동적 require의 경우, 예를 들어 require(`./modules/${name}.js`) 같은 코드는 동적 import()로 변환해야 합니다. const module = await import(`./modules/${name}.js`)처럼 Promise를 반환하므로 async/await를 사용해야 합니다. 여러분이 이 전환을 완료하면 번들 크기가 줄어들고(트리 쉐이킹 효과), 브라우저 네이티브 모듈 시스템을 활용할 수 있으며, 최신 JavaScript 표준을 따르는 유지보수하기 좋은 코드를 얻게 됩니다. ### 실전 팁 💡 package.json에 "type": "module"을 추가하면 .js 파일이 기본적으로 ESM으로 해석됩니다. 혼용이 필요하면 .cjs(CommonJS), .mjs(ESM) 확장자를 사용하세요. 💡 대량의 파일을 변환할 때는 jscodeshift나 codemod 도구를 사용하세요. 수동 변환보다 훨씬 빠르고 정확합니다. 💡 process.env.NODE_ENV 같은 Node.js 전용 변수는 Vite에서 import.meta.env.MODE로 대체해야 합니다. 브라우저 코드에는 process가 없습니다. 💡 순환 참조(circular dependency)가 있다면 전환 전에 먼저 해결하세요. ESM은 순환 참조를 다르게 처리하여 예상치 못한 undefined가 발생할 수 있습니다. 💡 TypeScript를 사용한다면 tsconfig.json의 module을 "ESNext"로, moduleResolution을 "bundler"로 설정하세요. Vite와 가장 잘 맞는 조합입니다. --- ## 5. 빌드_스크립트_수정사항 ### 시작하며 여러분이 package.json의 scripts 섹션에서 webpack 명령어로 가득 찬 복잡한 빌드 스크립트를 보면서, "이걸 다 바꿔야 하나?"라고 생각하신 적 있나요? 개발, 빌드, 프리뷰, 배포 등 각 단계마다 다른 Webpack 옵션과 플래그들이 사용되고, CI/CD 파이프라인에도 이런 스크립트들이 하드코딩되어 있습니다. 이런 복잡한 빌드 스크립트는 새로운 팀원이 프로젝트를 시작할 때 큰 장벽이 됩니다. "npm run build:prod"와 "npm run build:staging"의 차이가 무엇인지, 왜 이렇게 많은 플래그가 필요한지 이해하기 어렵습니다. 또한 Webpack 설정이 바뀔 때마다 스크립트도 함께 수정해야 하는 번거로움이 있습니다. 바로 이럴 때 필요한 것이 Vite의 간결한 빌드 명령어입니다. Vite는 개발과 프로덕션 빌드를 명확하게 분리하고, 대부분의 최적화를 자동으로 처리하여 스크립트를 최소화합니다. ### 개요 간단히 말해서, 빌드 스크립트 수정은 Webpack 기반의 복잡한 빌드 명령어들을 Vite의 간단하고 직관적인 명령어로 교체하는 작업입니다. Vite는 세 가지 핵심 명령어만 제공합니다: vite(개발 서버), vite build(프로덕션 빌드), vite preview(빌드 결과 미리보기). 예를 들어, Webpack에서 webpack-dev-server --mode development --hot --open 같은 긴 명령어가 필요했다면, Vite에서는 단순히 vite만 입력하면 개발 서버가 시작됩니다. 핫 모듈 리로딩(HMR)도 자동으로 활성화되죠. 기존에는 환경별로 다른 Webpack 설정 파일을 만들고(webpack.dev.js, webpack.prod.js), 각각에 대한 빌드 스크립트를 작성해야 했다면, 이제는 하나의 설정 파일과 간단한 스크립트로 모든 환경을 처리할 수 있습니다. 빌드 스크립트의 핵심 개선사항은 명령어 단순화, 환경 자동 감지, 최적화 기본 활성화입니다. 이러한 개선으로 package.json이 훨씬 깔끔해지고, 빌드 프로세스를 이해하기 쉬워집니다. ### 코드 예제 ```javascript // package.json - Webpack 스크립트 (기존) { "scripts": { "dev": "webpack serve --mode development --hot --open", "build": "webpack --mode production --progress", "build:analyze": "webpack --mode production --analyze", "build:staging": "webpack --mode production --env staging", "clean": "rimraf dist" } } // package.json - Vite 스크립트 (변환 후 - 훨씬 간결함) { "scripts": { "dev": "vite", // 개발 서버 (HMR 자동 포함) "build": "vite build", // 프로덕션 빌드 "preview": "vite preview", // 빌드 결과 로컬 테스트 "build:analyze": "vite build && vite-bundle-visualizer" } } // staging 환경은 .env.staging 파일로 관리 // clean은 불필요 (vite build가 자동으로 정리) ``` ### 설명 이것이 하는 일: 이 수정 과정은 여러 개의 복잡한 Webpack 명령어와 옵션들을 Vite의 간결한 명령어 체계로 통합하여, 빌드 프로세스를 누구나 쉽게 이해하고 실행할 수 있게 만듭니다. 첫 번째로, 개발 서버 명령어를 보면 Webpack은 webpack-dev-server를 별도로 실행하고 --mode, --hot, --open 등 여러 플래그를 명시해야 했습니다. Vite는 단순히 vite 명령어만 실행하면 개발 서버가 시작되고, HMR이 자동으로 활성화되며, vite.config.js의 server.open 옵션으로 브라우저 자동 열기를 제어할 수 있습니다. 이렇게 옵션을 설정 파일로 옮기면 명령어가 간결해지고 재사용하기 쉬워집니다. 그 다음으로, 프로덕션 빌드를 살펴보면 Webpack은 --mode production 플래그로 프로덕션 모드를 활성화하고, 이에 따라 코드 압축, 트리 쉐이킹, 소스맵 제거 등이 실행됩니다. Vite에서는 vite build 명령어가 자동으로 프로덕션 모드로 실행되며, 모든 최적화가 기본적으로 활성화됩니다. Rollup 기반의 강력한 번들링으로 코드를 최적으로 분할하고 압축합니다. 세 번째로, 환경별 빌드를 보면 Webpack은 --env 플래그나 별도의 설정 파일로 처리했지만, Vite는 .env 파일 시스템을 사용합니다. .env.development, .env.production, .env.staging 파일을 만들고, vite build --mode staging 같은 명령어로 원하는 환경을 선택할 수 있습니다. 각 파일의 VITE_ 접두사 변수들이 자동으로 로드됩니다. 네 번째로, 빌드 결과를 로컬에서 테스트할 때 Webpack은 별도의 http-server나 serve 패키지를 설치해야 했지만, Vite는 vite preview 명령어를 제공합니다. 이 명령어는 빌드된 파일을 프로덕션과 유사한 환경에서 서빙하여, 배포 전에 최종 확인을 할 수 있게 해줍니다. 여러분이 이런 스크립트 수정을 완료하면 CI/CD 설정이 간단해지고, 새 팀원이 프로젝트를 클론받아 바로 시작할 수 있으며, 빌드 관련 문서와 유지보수 비용이 크게 줄어듭니다. ### 실전 팁 💡 vite --port 3000 --host로 포트와 호스트를 명령줄에서 바로 지정할 수 있습니다. 하지만 자주 사용하는 옵션은 vite.config.js에 넣는 것이 좋습니다. 💡 타입 체크가 필요하면 "build": "tsc --noEmit && vite build"처럼 TypeScript 컴파일러를 먼저 실행하세요. Vite는 타입 체크를 하지 않고 빠르게 트랜스파일만 합니다. 💡 GitHub Actions나 GitLab CI에서 빌드할 때는 vite build --mode production을 명시적으로 사용하여 환경을 확실히 하세요. 💡 번들 크기를 분석하려면 rollup-plugin-visualizer를 설치하고, vite.config.js에 플러그인으로 추가하면 빌드 후 자동으로 리포트가 생성됩니다. 💡 Docker 컨테이너에서 개발 서버를 실행할 때는 vite --host 0.0.0.0을 사용해야 외부에서 접근할 수 있습니다. --- ## 6. 마이그레이션_후_성능_비교_및_트러블슈팅 ### 시작하며 여러분이 마침내 Webpack에서 Vite로 마이그레이션을 완료했는데, "정말 성능이 개선되었나?", "혹시 놓친 문제는 없나?"라는 의문이 드실 겁니다. 마이그레이션 자체는 성공했지만, 실제 개발 경험이 얼마나 개선되었는지, 빌드 시간이 정말 빨라졌는지 측정하지 않으면 변화를 체감하기 어렵습니다. 이런 성능 비교는 단순한 숫자 확인을 넘어서 마이그레이션의 가치를 증명하는 과정입니다. 또한 마이그레이션 후 나타날 수 있는 미묘한 버그나 호환성 문제들을 조기에 발견하여 해결할 수 있는 기회입니다. import 경로 문제, 환경변수 누락, 타사 라이브러리 호환성 등 다양한 이슈가 발생할 수 있습니다. 바로 이럴 때 필요한 것이 체계적인 성능 측정과 일반적인 문제 해결 가이드입니다. 주요 지표를 측정하고, 흔히 발생하는 문제의 해결책을 미리 알고 있으면 마이그레이션을 안정적으로 마무리할 수 있습니다. ### 개요 간단히 말해서, 성능 비교와 트러블슈팅은 Webpack과 Vite의 실제 성능 차이를 정량적으로 측정하고, 마이그레이션 후 발생할 수 있는 일반적인 문제들을 신속하게 해결하는 과정입니다. 성능 측정은 개발 서버 시작 시간, 핫 모듈 리로딩(HMR) 속도, 프로덕션 빌드 시간, 최종 번들 크기 등 여러 지표를 포함합니다. 예를 들어, 중간 규모의 React 프로젝트에서 Webpack은 개발 서버가 30-60초 걸리는 반면, Vite는 1-2초 내에 시작됩니다. HMR도 Webpack은 1-3초 걸리지만 Vite는 거의 즉시(100-300ms) 반영됩니다. 이런 차이가 하루 종일 개발할 때 누적되면 엄청난 생산성 향상으로 이어집니다. 기존에는 빌드가 느려서 작은 수정도 확인하기 어려웠고, 빌드 최적화에 많은 시간을 투자해야 했다면, 이제는 빌드 성능 걱정 없이 개발에만 집중할 수 있습니다. 트러블슈팅의 핵심 영역은 모듈 해석 오류, 환경변수 문제, 써드파티 라이브러리 호환성입니다. 이러한 영역의 일반적인 문제와 해결책을 알고 있으면 마이그레이션 후 안정화 시간을 크게 단축할 수 있습니다. ### 코드 예제 ```javascript // 성능 측정 스크립트 import { performance } from 'perf_hooks'; // 개발 서버 시작 시간 측정 console.log('⏱️ 성능 측정 시작'); const startTime = performance.now(); // vite.config.js에서 사용 export default defineConfig({ plugins: [{ name: 'performance-monitor', configResolved() { const loadTime = performance.now() - startTime; console.log(`✅ Vite 설정 로드: ${loadTime.toFixed(2)}ms`); }, buildStart() { console.log('🔨 빌드 시작:', new Date().toLocaleTimeString()); }, buildEnd() { const buildTime = performance.now() - startTime; console.log(`✅ 빌드 완료: ${(buildTime / 1000).toFixed(2)}s`); } }] }); // 일반적인 트러블슈팅 - 모듈 해석 오류 해결 export default defineConfig({ resolve: { extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json'], alias: { '@': path.resolve(__dirname, './src'), '~': path.resolve(__dirname, './src') } } }); ``` ### 설명 이것이 하는 일: 이 측정과 트러블슈팅 과정은 마이그레이션의 실질적인 효과를 수치로 확인하고, 발생할 수 있는 문제들을 사전에 예방하거나 신속하게 해결합니다. 첫 번째로, 개발 서버 시작 시간을 측정하면 Vite의 가장 큰 장점을 확인할 수 있습니다. Webpack은 모든 파일을 번들링한 후 서버를 시작하지만, Vite는 네이티브 ESM을 사용하여 요청이 들어온 파일만 즉시 변환하므로 서버가 거의 즉시 시작됩니다. 프로젝트에 1000개 파일이 있어도 초기 로딩에는 10-20개 파일만 필요할 수 있고, Vite는 이것만 처리합니다. 그 다음으로, HMR 성능을 측정하면 개발 경험의 극적인 개선을 체감할 수 있습니다. Webpack의 HMR은 변경된 모듈과 의존 관계에 있는 모든 모듈을 다시 번들링하지만, Vite는 변경된 모듈만 교체하고 브라우저의 ESM import를 활용하여 즉시 반영합니다. 코드를 저장하면 거의 지연 없이 결과를 볼 수 있죠. 세 번째로, 일반적인 트러블슈팅 사례를 보면 "Cannot find module" 오류가 가장 흔합니다. 이는 Webpack과 Vite의 모듈 해석 방식 차이 때문입니다. Webpack은 확장자를 생략해도 자동으로 찾아주지만, Vite는 명시적인 확장자를 권장합니다. resolve.extensions에 필요한 확장자를 추가하거나, import 문에 .js, .ts 등을 명시하면 해결됩니다. 네 번째로, 환경변수 문제도 자주 발생합니다. Webpack의 process.env.REACT_APP_API_URL을 Vite의 import.meta.env.VITE_API_URL로 바꿔야 하며, 모든 환경변수에 VITE_ 접두사를 붙여야 합니다. 이는 보안을 위한 것으로, 실수로 민감한 서버 환경변수가 클라이언트에 노출되는 것을 방지합니다. 다섯 번째로, 일부 오래된 npm 패키지는 CommonJS만 제공하여 Vite와 호환되지 않을 수 있습니다. 이 경우 optimizeDeps.include에 해당 패키지를 추가하면 Vite가 사전 번들링하여 ESM으로 변환합니다. 여러분이 이런 성능 측정과 트러블슈팅을 완료하면 마이그레이션의 성공을 확신할 수 있고, 팀원들에게 구체적인 개선 효과를 공유할 수 있으며, 향후 유사한 문제가 발생했을 때 빠르게 대응할 수 있는 경험을 얻게 됩니다. ### 실전 팁 💡 Chrome DevTools의 Network 탭에서 Throttling을 "Fast 3G"로 설정하고 개발하면, HMR 속도를 더 정확히 체감할 수 있습니다. 💡 빌드 시간이 여전히 느리다면 build.rollupOptions.output.manualChunks로 큰 라이브러리를 분리하세요. React, Lodash 등을 별도 청크로 나누면 캐싱 효과가 좋습니다. 💡 "Uncaught SyntaxError: Unexpected token" 오류가 발생하면, 대부분 Node.js 전용 코드가 브라우저에 포함된 것입니다. ssr.noExternal로 서버 전용으로 표시하세요. 💡 성능 비교 리포트를 작성하여 팀과 공유하세요. 구체적인 숫자로 개선 효과를 보여주면 마이그레이션 결정에 대한 신뢰가 높아집니다. 💡 마이그레이션 후 일주일 정도는 모니터링 기간으로 두고, 사용자나 팀원의 피드백을 적극적으로 수집하세요. 예상치 못한 엣지 케이스를 발견할 수 있습니다. ---