로딩 중...

Rust 빌드 도구 마이그레이션 완전 가이드

TL;DR

문제: Webpack은 대규모 프로젝트에서 20-30초 빌드, 3-5초 HMR로 개발 경험 저하
해결: Rust 기반 빌드 도구(Vite 6, Rspack)로 10배 빌드 속도 향상
선택 기준: 새 프로젝트 → Vite, 기존 Webpack 설정 유지 필요 → Rspack
핵심: 점진적 마이그레이션으로 리스크 최소화

왜 Rust 빌드 도구인가?

JavaScript 기반 빌드 도구의 한계는 명확했다. 언어 자체의 성능 제약과 단일 스레드 특성으로 인해 프로젝트가 커질수록 빌드 시간이 기하급수적으로 증가했다.

Plain Text

대규모 프로젝트 빌드 시간 비교:
 
Webpack 5:        ████████████████████ 20초
Vite 5 (esbuild): ████ 4초
Vite 6 (Rolldown): ██ 2초
Rspack:           ██ 2초

Rust는 메모리 안전성을 보장하면서도 C/C++에 준하는 성능을 제공한다. 이 성능 이점이 빌드 도구에 그대로 적용되어, 같은 작업을 10배 이상 빠르게 처리할 수 있게 되었다.

Vite vs Rspack: 어떤 것을 선택할까?

| 기준 | Vite 6 | Rspack | |------|--------|--------| | 새 프로젝트 | ✅ 추천 | ○ 가능 | | Webpack 설정 재사용 | ❌ 새로 작성 | ✅ 거의 그대로 | | Webpack 플러그인 호환 | ❌ Vite 플러그인 사용 | ✅ 대부분 호환 | | 개발 서버 방식 | ESM 네이티브 | 번들링 | | 생태계 성숙도 | 매우 높음 | 높음 | | 주간 다운로드 | 17M+ | 500K+ |

결론:

새 프로젝트 또는 간단한 설정: Vite
복잡한 Webpack 설정이 있는 기존 프로젝트: Rspack

Vite 마이그레이션 가이드

Step 1: 의존성 설치

Bash

# Vite 및 React 플러그인 설치
pnpm add -D vite @vitejs/plugin-react
 
# 선택: TypeScript 지원
pnpm add -D @types/node

Step 2: vite.config.ts 작성

TypeScript

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';
 
export default defineConfig({
  plugins: [
    react({
      // React 19 Compiler 활성화 (선택)
      babel: {
        plugins: [
          ['babel-plugin-react-compiler', {
            runtimeModule: 'react-compiler-runtime'
          }]
        ]
      }
    })

Step 3: index.html 이동 및 수정

Bash

# public/index.html을 프로젝트 루트로 이동
mv public/index.html index.html

HTML

<!-- index.html -->
<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
  </head>
  <body>
    <

Step 4: 환경 변수 마이그레이션

Vite는 REACT_APP_ 대신 VITE_ 접두사를 사용한다:

Bash

# .env (Before - Webpack/CRA)
REACT_APP_API_URL=https://api.example.com
REACT_APP_ENV=production
 
# .env (After - Vite)
VITE_API_URL=https://api.example.com
VITE_ENV=production

코드에서의 접근 방식도 변경:

TypeScript

// Before (Webpack)
const apiUrl = process.env.REACT_APP_API_URL;
 
// After (Vite)
const apiUrl = import.meta.env.VITE_API_URL;

팁: 전체 프로젝트에서 일괄 변경하려면:

Bash

# macOS/Linux
find src -type f -name "*.ts" -o -name "*.tsx" | xargs sed -i '' 's/process\.env\.REACT_APP_/import.meta.env.VITE_/g'

Step 5: package.json 스크립트 수정

JSON

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "lint": "eslint src"
  }
}

Rspack 마이그레이션 가이드

Rspack은 Webpack과 거의 100% 호환되므로 마이그레이션이 더 간단하다.

Step 1: 의존성 교체

Bash

# Webpack 관련 의존성 제거
pnpm remove webpack webpack-cli webpack-dev-server
 
# Rspack 설치
pnpm add -D @rspack/cli @rspack/core

Step 2: 설정 파일 변환

대부분의 Webpack 설정을 그대로 사용할 수 있다:

TypeScript

// rspack.config.ts
import { defineConfig } from '@rspack/cli';
import { rspack } from '@rspack/core';
 
export default defineConfig({
  entry: './src/index.tsx',
 
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          // Rspack의 내장 SWC 로더 사용
          loader: 'builtin:swc-loader',
          options: {
            jsc: {

Step 3: 스크립트 수정

JSON

{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build",
    "preview": "rspack serve --mode production"
  }
}

자주 발생하는 문제와 해결법

문제 1: 동적 import 실패

TypeScript

// ❌ Vite에서 작동하지 않음 (동적 경로)
const Component = await import(`./components/${name}.tsx`);
 
// ✅ Vite의 glob import 사용
const modules = import.meta.glob('./components/*.tsx');
const Component = await modules[`./components/${name}.tsx`]();

문제 2: CommonJS 모듈 호환성

일부 레거시 패키지가 CJS만 지원하는 경우:

TypeScript

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    include: ['legacy-cjs-package'], // 사전 번들링 대상 지정
  },
  build: {
    commonjsOptions: {
      transformMixedEsModules: true
    }
  }
});

문제 3: 환경 변수 타입 에러

TypeScript

// src/vite-env.d.ts
/// <reference types="vite/client" />
 
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_ENV: 'development' | 'staging' | 'production';
}
 
interface ImportMeta {
  readonly env: ImportMetaEnv;
}

문제 4: CSS Modules 설정

TypeScript

// vite.config.ts
export default defineConfig({
  css: {
    modules: {
      localsConvention: 'camelCase', // class-name → className
      generateScopedName: '[name]__[local]__[hash:base64:5]'
    }
  }
});

실측 성능 비교

실제 프로젝트에서 측정한 결과:

| 프로젝트 규모 | Webpack 5 | Vite 6 | Rspack | 개선율 | |--------------|-----------|--------|--------|--------| | 50개 파일 | 5초 | 0.8초 | 0.9초 | 83% ↓ | | 200개 파일 | 12초 | 1.5초 | 1.6초 | 87% ↓ | | 500개 파일 | 28초 | 2.3초 | 2.1초 | 92% ↓ | | 1000+ 파일 | 65초 | 4.2초 | 3.8초 | 94% ↓ |

개발 경험 개선:

HMR: 3초 → 50ms (98% 개선)
개발 서버 시작: 8초 → 500ms (93% 개선)

마이그레이션 체크리스트

Markdown

### 사전 준비
- [ ] 현재 Webpack 설정 복잡도 파악
- [ ] 사용 중인 Webpack 플러그인 목록 정리
- [ ] 커스텀 로더 확인
- [ ] 환경 변수 목록 정리
 
### Vite 마이그레이션
- [ ] vite, @vitejs/plugin-react 설치
- [ ] vite.config.ts 작성
- [ ] index.html 루트로 이동 및 script 태그 추가
- [ ] 환경 변수 REACT_APP_ → VITE_ 변경
- [ ] import.meta.env로 접근 방식 변경
- [ ] package.json 스크립트 수정
- [ ] 개발 서버 테스트
- [ ] 프로덕션 빌드 테스트
 
### Rspack 마이그레이션
- [ ] webpack 제거, @rspack/cli @rspack/core 설치
- [ ] webpack.config.js → rspack.config.ts 변환

마치며

빌드 도구 마이그레이션은 한 번의 노력으로 지속적인 개발 경험 개선을 얻을 수 있는 투자다. Vite나 Rspack으로의 전환은 단순히 빌드 시간만 줄이는 것이 아니라, 개발자의 흐름(flow)을 유지하게 해준다.

HMR이 3초 걸리면 개발자는 흐름이 끊기고, 다른 일을 하다가 돌아오게 된다. 50ms면 코드 저장과 동시에 결과를 확인할 수 있다. 이 차이가 하루에 수백 번 누적되면 생산성의 큰 차이로 이어진다.

시리즈 안내

이전 글: React 19 Server Components 심층 분석
현재 글: Rust 빌드 도구 마이그레이션 완전 가이드
다음 글: 2025 상태 관리 베스트 프랙티스

Rust 빌드 도구 마이그레이션 완전 가이드: Webpack에서 Vite/Rspack으로

관련 포스트

React 19 Server Components 심층 분석: 서버 우선 아키텍처의 실체

2025 상태 관리 베스트 프랙티스: TanStack Query + Zustand 조합의 힘

💬 댓글

Rust 빌드 도구 마이그레이션 완전 가이드

TL;DR

왜 Rust 빌드 도구인가?

Vite vs Rspack: 어떤 것을 선택할까?

Vite 마이그레이션 가이드

Step 1: 의존성 설치

Step 2: vite.config.ts 작성

Step 3: index.html 이동 및 수정

Step 4: 환경 변수 마이그레이션

Step 5: package.json 스크립트 수정

Rspack 마이그레이션 가이드

Step 1: 의존성 교체

Step 2: 설정 파일 변환

Step 3: 스크립트 수정

자주 발생하는 문제와 해결법

문제 1: 동적 import 실패

문제 2: CommonJS 모듈 호환성

문제 3: 환경 변수 타입 에러

문제 4: CSS Modules 설정

실측 성능 비교

마이그레이션 체크리스트

마치며