[Vite defineConfig 설정 기본편] root, base, plugins, resolve, build, 상황별 예시

 

1. 🧱 defineConfig()와 설정 구조 개요

Vite는 ESM 기반의 번들러로, vite.config.ts 또는 .js 파일을 통해 설정을 제공합니다.

이 설정 파일에서 defineConfig()는 타입 지원과 자동 완성을 위한 래퍼입니다.

// 기본 구조
import { defineConfig } from 'vite';

export default defineConfig({
  root: '.',           // 프로젝트 루트 (index.html 기준)
  plugins: [],         // 플러그인 배열
  resolve: {},         // 경로 해석 관련 설정
  build: {},           // 빌드 설정 (rollup 옵션 포함)
});

 

---

2. 🔍 주요 설정 속성 복기 및 해설

✅ root

• 기본값: process.cwd()
• 설명: 프로젝트의 루트 디렉토리 설정. 이 디렉토리 기준으로 index.html, src 등이 해석됨.
• 예시:

root: './demo', // ./demo/index.html이 엔트리로 사용됨

---

✅ base

• 기본값: '/'
• 설명: 빌드시 생성되는 자산의 URL prefix. CDN 경로 지정 등 외부 환경 대응에 사용.
• 예시:

base: './', // 상대 경로로 자산 import (file:// 테스트용)
base: '/static/', // Nginx 서브경로 대응

---

✅ plugins

• 설명: Vite의 플러그인 생태계 또는 Rollup 플러그인 포함 가능
• 주요 예시:

plugins: [
  react(),                   // @vitejs/plugin-react-swc
  tsconfigPaths(),           // tsconfig.json 기반 경로 alias
  removeCrossoriginPlugin()  // 커스텀 HTML 수정 플러그인
]

---

✅ resolve

• 설명: 모듈 import 경로를 해석하는 방식 지정 (alias 등)
• 예시:

resolve: {
  alias: {
    '@editor': path.resolve(__dirname, 'src/editor'),
  }
}

---

✅ build

• 설명: Vite → Rollup 기반 빌드 설정
• 주요 속성:

build: {
  outDir: 'dist',                 // 출력 디렉토리
  assetsDir: 'assets',           // 정적 자산 폴더
  sourcemap: true,               // sourcemap 생성 여부
  target: 'es2020',              // 트랜스파일 타겟
  minify: 'esbuild',             // 'terser' or 'esbuild'
  rollupOptions: {
    input: './index.html',       // HTML 엔트리 명시 (멀티페이지 대응 시 유용)
    output: {
      entryFileNames: `assets/[name]-[hash].js`,
      chunkFileNames: `assets/[name]-[hash].js`,
      assetFileNames: `assets/[name]-[hash].[ext]`,
    },
  },
  emptyOutDir: true,             // 기존 dist 제거 여부
}

---

3. 🧩 설정 상황 예시

🎯 A. 파일 시스템 기반 로딩 테스트 (file:// 환경 대응)

export default defineConfig({
  base: './', // 상대 경로로 경로 지정
  plugins: [
    {
      name: 'remove-crossorigin',
      transformIndexHtml(html) {
        return html.replace(/<script type="module" crossorigin/g, '<script type="module"');
      }
    }
  ]
});

 

🔥 B. 외부 CDN 자산 사용

export default defineConfig({
  base: 'https://cdn.mycdn.com/myapp/',
});

 

🧩 C. 라이브러리 번들링 용도 (build.lib)

export default defineConfig({
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      fileName: format => `my-lib.${format}.js`
    },
    rollupOptions: {
      external: ['react'],
      output: {
        globals: {
          react: 'React'
        }
      }
    }
  }
});

---

🧠 마무리 팁

• vite build는 Rollup을 래핑한 고수준 추상화임.
• 파일 경로, publicPath(base), asset 위치 정책이 명확하지 않으면 정적 배포에서 이슈가 빈번하게 발생함.
• 로컬에서 file://로 열 경우엔 crossorigin, base, 상대경로의 정합성이 매우 중요함.
• 다중 HTML 엔트리를 사용하는 경우 rollupOptions.input을 꼭 명시할 것.