Skip to content

v2에서 마이그레이션하기

지원하는 Node.js 버전

Vite는 EOL(End-of-life)에 도달한 Node.js 12 / 13 / 15 를 더 이상 지원하지 않습니다. Node.js 버전 14.18+ 또는 16+ 을 사용해주세요.

최신 브라우저 기준 변경

프로덕션 버전으로 빌드 및 번들링 시, 소스 코드가 최신 JavaScript를 지원하는 환경에서 동작한다고 가정하고 진행됩니다. 기존적으로 Vite는 네이티브 ES 모듈, 네이티브 ESM의 동적 Import, 그리고 import.meta를 지원하는 브라우저를 대상으로 하고 있습니다:

  • Chrome >=87
  • Firefox >=78
  • Safari >=13
  • Edge >=88

만약 이보다 이전 버전의 브라우저를 대상으로 한다면 @vitejs/plugin-legacy 플러그인을 사용해주세요. 이 플러그인은 자동으로 레거시 청크 및 ES 언어 기능에 대한 폴리필을 생성합니다.

설정 옵션 관련 변경 사항

아래의 옵션은 이미 Vite v2에서 사용되지 않는 옵션이었으며, v3에서는 제거되었습니다:

아키텍처 변경과 레거시 옵션들

이 섹션에서는 Vite v3 아키텍처에 대한 가장 큰 변경 사항에 대해 설명합니다. 만약 호환성 문제가 있는 경우, 프로젝트를 v2에서 마이그레이션 할 수 있도록 Vite v2 전략으로 되돌리는 레거시 옵션이 존재합니다.

개발 서버 관련 변경 사항

Vite 개발 서버의 기본 포트 번호는 이제 5173 입니다. 물론 server.port 옵션을 이용해 3000으로 설정할 수 있습니다.

Vite's default dev server host is now localhost. In Vite v2, Vite was listening to 127.0.0.1 by default. Node.js under v17 normally resolves localhost to 127.0.0.1, so for those versions, the host won't change. For Node.js 17+, you can use server.host to set it to 127.0.0.1 to keep the same host as Vite v2.

Note that Vite v3 now prints the correct host. This means Vite may print 127.0.0.1 as the listening host when localhost is used. You can set dns.setDefaultResultOrder('verbatim') to prevent this. See server.host for more details.

SSR 관련 변경 사항

Vite v3는 기본적으로 SSR 빌드 시 ESM을 타깃으로 합니다. ESM을 사용하게 되면 SSR 외부화 휴리스틱은 더 이상 필요하지 않기 때문이죠. ssr.noExternal 옵션을 이용해 SSR 번들에 포함될 디펜던시를 설정할 수도 있습니다.

프로젝트에서 SSR용 ESM을 사용할 수 없는 경우라면, legacy.buildSsrCjsExternalHeuristics 옵션을 이용해 Vite v2와 동일한 외부화 방식을 사용하는 CJS 번들 생성이 가능합니다.

또한 build.rollupOptions.output.inlineDynamicImports 옵션은 이제 ssr.target'node'일 때 기본적으로 false가 됩니다. 따라서 Node.js 빌드 시 inlineDynamicImports로 인해 발생되는 실행 순서 변경이나 단일 파일로 번들링되지 않습니다.

일반적인 변경 사항

  • SSR 및 lib 모드에서 빌드된 JS 파일의 확장자는 이제 포맷과 패키지 타입에 따라 올바른 확장자(js, mjs, 또는 cjs)를 갖습니다.
  • Terser는 이제 선택적인(Optional) 디펜던시입니다. 필요한 경우 build.minify: 'terser' 옵션과 함께 이 디펜던시를 설치해주세요.
    shell
    npm add -D terser

import.meta.glob

  • Raw에 대한 import.meta.glob 옵션이 { assert: { type: 'raw' }}에서 { as: 'raw' }으로 변경되었습니다.

  • import.meta.glob의 키는 이제 현재 모듈에 상대적으로 설정할 수 있습니다.

    diff
    // 파일: /foo/index.js
    const modules = import.meta.glob('../foo/*.js')
    
    // 변환된 코드:
    const modules = {
    -  '../foo/bar.js': () => {}
    +  './bar.js': () => {}
    }
  • import.meta.glob과 함께 별칭을 사용하는 경우에는 키 값이 항상 절대적인 위치를 가리키게 됩니다.

  • import.meta.globEager 옵션은 더 이상 사용되지 않습니다. 이 대신 import.meta.glob('*', { eager: true })을 사용해주세요.

WebAssembly 지원 관련

"ESM integration for Wasm"과의 향후 충돌을 방지하지 위해 import init from 'example.wasm' 구문이 삭제되었습니다. 이 대신 ?init 접미사를 사용해주세요.

diff
-import init from 'example.wasm'
+import init from 'example.wasm?init'

-init().then((exports) => {
+init().then(({ exports }) => {
  exports.test()
})

자동으로 https 인증서 생성하기

https 옵션을 사용할 때는 유효한 인증서가 필요합니다. Vite v2에서는 인증서가 존재하지 않은 경우 자체적으로 서명된 인증서를 만든 뒤 캐싱했었습니다. Vite v3부터는 인증서를 직접 수동으로 생성하는 것을 권고하지만, v2의 인증서 자동 생성 방식을 계속 사용하고자 한다면 프로젝트에 @vitejs/plugin-basic-ssl 플러그인을 추가해주세요.

js
import basicSsl from '@vitejs/plugin-basic-ssl'

export default {
  plugins: [basicSsl()]
}

실험적 기능

빌드 시 esbuild 디펜던시 최적화 사용하기

Vite v3에서는 esbuild를 사용해 빌드 시 디펜던시를 최적화할 수 있습니다. 이를 활성화하면 Vite v2에 있었던 개발 버전과 프로덕션 버전 사이의 중요한 차이점 중 하나가 사라지게 됩니다. esbuild는 CJS 포맷의 디펜던시를 ESM으로 변환하기 때문에 @rollup/plugin-commonjs는 더 이상 사용하지 않아도 됩니다.

이 빌드 방식을 사용하고자 한다면 optimizeDeps.disabled 옵션의 값을 false로 설정해주세요(v3의 기본값은 disabled: 'build' 입니다). @rollup/plugin-commonjsbuild.commonjsOptions: { include: [] }로 제거할 수 있습니다.

고급

아래는 Vite 관련 플러그인 또는 툴 개발자에게만 영향을 미치는 몇 가지 변경 사항들에 대한 내용입니다.

아래는 일부 사용자에게만 영향을 미치는 변경 사항입니다.

v1에서 마이그레이션하기

v1에서 마이그레이션하기 문서를 먼저 확인해 앱을 Vite v2로 마이그레이션 한 다음, 이 페이지에서 언급된 내용을 확인해 v3로 마이그레이션을 진행해주세요.

Released under the MIT License.