[번역+추가내용] Vite v5에서 v6로 마이그레이션 하기

Environment API

새로운 실험적 Environment API의 일환으로 큰 내부 리팩토링이 필요했습니다. Vite 6는 대부분의 프로젝트가 새로운 메이저 버전으로 빠르게 업그레이드할 수 있도록 호환성을 깨지 않으려 노력했습니다. 생태계의 대부분이 새 API를 안정적으로 사용하기 시작할 때까지 기다릴 예정입니다. 일부 엣지 케이스가 있을 수 있지만, 이는 주로 프레임워크와 도구의 저수준 사용에만 영향을 미칠 것입니다. 릴리스 전에 생태계의 메인테이너들과 협력하여 이러한 차이점들을 완화했습니다. 문제점을 발견하시면 이슈를 열어주세요.

 

Vite의 구현 변경으로 인해 일부 내부 API가 제거되었습니다. 이러한 API를 사용하고 계셨다면 기능 요청을 해주시기 바랍니다.

Vite Runtime API

실험적인 Vite Runtime API는 Module Runner API로 발전했으며, 이는 Vite 6에서 새로운 실험적 Environment API의 일부로 출시되었습니다. 이 기능이 실험적이었기 때문에 Vite 5.1에서 도입된 이전 API의 제거는 호환성을 깨뜨리는 변경사항은 아니지만, 사용자들은 Vite 6로 마이그레이션하면서 Module Runner에 맞게 코드를 업데이트해야 합니다.

 

주요 변경점
1. 임포트 경로 변경: vite/runtime → vite/module-runner
2. API 이름 변경: createViteRuntime → createModuleRunner
3. 인스턴스 메서드 변경: runtime.destroy() → runner.close()
4. Environment API의 일부로 통합됨

 

서버사이드 렌더링이나 runner가 필요한 테스트 환경에서 주로 사용

(그런데 서버사이드 렌더링은 프레임 워크를 주로 사용하기 때문에 직접 구축하는 것이 아니라면 사용할 일이 없어보입니다)

import { createModuleRunner } from 'vite/module-runner';
import express from 'express';

const app = express();

app.get('*', async (req, res) => {
const runner = await createModuleRunner({
root: process.cwd(),
});

try {
// SSR 엔트리 포인트 모듈 실행
const { render } = await runner.executeUrl('./src/entry-server.tsx');

// 클라이언트 요청 URL에 대한 HTML 렌더링
const html = await render({ url: req.originalUrl });

res.status(200).set({ 'Content-Type': 'text/html' }).end(html);
} catch (e) {
console.error(e);
res.status(500).end('서버 오류가 발생했습니다');
} finally {
await runner.close();
}
});

app.listen(3000);

일반적인 변경사항

resolve.conditions의 기본값

 

이 변경사항은 resolve.conditions / ssr.resolve.conditions / ssr.resolve.externalConditions를 설정하지 않은 사용자에게는 영향을 미치지 않습니다.

 

Vite 5에서는 resolve.conditions의 기본값이 []였고 일부 조건이 내부적으로 추가되었습니다.

ssr.resolve.conditions의 기본값은 resolve.conditions의 값이었습니다.

// vite.config.ts (Vite 5)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
plugins: [react()],
// resolve.conditions를 명시적으로 설정하지 않음
// 내부적으로 'module', 'browser', 'development/production' 조건이 추가됨

// SSR 설정
ssr: {
// ssr.resolve.conditions를 명시적으로 설정하지 않음
// 기본적으로 resolve.conditions 값을 상속
}

 

Vite 6부터는 일부 조건이 더 이상 내부적으로 추가되지 않으며 설정값에 포함되어야 합니다.

• resolve.conditions: ['module', 'browser', 'development|production']
• ssr.resolve.conditions: ['module', 'node', 'development|production']

// vite.config.ts (Vite 6)
import { defineConfig, defaultClientConditions, defaultServerConditions } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
plugins: [react()],
resolve: {
// 이제 명시적으로 조건을 설정해야 함
conditions: defaultClientConditions // ['module', 'browser', 'development/production']
},

// SSR 설정
ssr: {
resolve: {
// 이제 명시적으로 서버 조건을 설정해야 함
conditions: defaultServerConditions // ['module', 'node', 'development/production']
}
}
})

 

이러한 옵션의 기본값은 해당 값으로 업데이트되었으며, ssr.resolve.conditions는 더 이상 기본값으로 resolve.conditions를 사용하지 않습니다. development|production은 process.env.NODE_ENV의 값에 따라 production 또는 development로 대체되는 특수 변수입니다. 이러한 기본값은 vite에서 defaultClientConditions와 defaultServerConditions로 내보내집니다.

 

resolve.conditions 또는 ssr.resolve.conditions에 사용자 정의 값을 지정한 경우, 새 조건을 포함하도록 업데이트해야 합니다. 예를 들어, 이전에 resolve.conditions에 ['custom']을 지정했다면, 대신 ['custom', ...defaultClientConditions]를 지정해야 합니다.

 

이런 식으로 조건에 따라 진입점을 정의해둔 경우에 해당합니다.

// 라이브러리의 package.json
{
  "name": "my-component-library",
  "exports": {
    ".": {
      "mobile": "./dist/mobile.js",
      "desktop": "./dist/desktop.js",
      "dark": "./dist/dark-theme.js",
      "light": "./dist/light-theme.js",
      "default": "./dist/index.js"
    }
  }
}

JSON stringify

Vite 5에서는 json.stringify: true로 설정했을 때 json.namedExports가 비활성화되었습니다.

// vite.config.ts (Vite 5)
import { defineConfig } from 'vite'

export default defineConfig({
  json: {
    stringify: true, // JSON을 문자열로 변환하고 namedExports 비활성화
    namedExports: true // 기본값이지만 stringify: true일 때 무시됨
  }
})

// Vite 5에서 JSON 임포트 결과
import data from './data.json'
console.log(data) // JSON 파일 내용이 문자열로 변환됨: "{"name":"홍길동","age":30}"

 

Vite 6부터는 json.stringify: true로 설정해도 json.namedExports가 비활성화되지 않으며 해당 값이 존중됩니다. 이전 동작을 원하시면 json.namedExports: false로 설정하시면 됩니다.

또한 Vite 6는 json.stringify의 새로운 기본값으로 'auto'를 도입했으며, 이는 큰 JSON 파일만 문자열화합니다. 이 동작을 비활성화하려면 json.stringify: false로 설정하세요.

// vite.config.ts (Vite 6)
import { defineConfig } from 'vite'

export default defineConfig({
  json: {
    stringify: true, // JSON을 문자열로 변환하지만 namedExports 설정은 영향 없음
    namedExports: true // 이제 stringify: true와 함께 사용 가능
  }
})

// Vite 6에서 JSON 임포트 결과 (stringify: true, namedExports: true)
import data, { name, age } from './data.json'
console.log(data) // JSON 파일 내용이 문자열로 변환됨: "{"name":"홍길동","age":30}"
console.log(name) // "홍길동" - 명명된 내보내기도 사용 가능
console.log(age) // 30 - 명명된 내보내기도 사용 가능

HTML 요소의 에셋 참조에 대한 확장된 지원

Vite 5에서는 <link href>, <img src> 등과 같은 일부 지원되는 HTML 요소만 Vite에 의해 처리되고 번들링될 에셋을 참조할 수 있었습니다. 다른 요소나 속성에 있는 파일 경로는 그대로 유지되어 번들링이나 최적화가 되지 않았습니다.

<!-- Vite 5에서 처리되는 에셋 참조 -->
<link href="./styles/main.css" rel="stylesheet">
<img src="./images/logo.png" alt="로고">
<script src="./scripts/main.js"></script>

 

이로 인해, 다음과 같은 문제가 발생합니다.

 

- 파일 경로가 빌드 후 구조에 맞게 업데이트되지 않음
- 에셋이 번들링되지 않아 별도의 HTTP 요청 발생
- 최적화(압축, 변환 등)가 적용되지 않음
- 해시 기반 캐싱 혜택을 받지 못함

 

Vite 6는 더 많은 HTML 요소에 대한 지원을 확장합니다. 전체 목록은 HTML 기능 문서에서 확인할 수 있습니다.

<!-- Vite 6에서는 이 모든 요소가 처리됨 -->
<video src="./video.mp4"></video>
<audio src="./audio.mp3"></audio>
<div style="background-image: url('./pattern.png')"></div>

<!-- 빌드 후 -->
<video src="/assets/video.a1b2c3d4.mp4"></video>
<audio src="/assets/audio.e5f6g7h8.mp3"></audio>
<div style="background-image: url('/assets/pattern.i9j0k1l2.png')"></div>

 

 

특정 요소에서 HTML 처리를 제외하려면 해당 요소에 vite-ignore 속성을 추가할 수 있습니다.

<!-- 이 요소는 Vite에 의해 처리되지 않음 -->
<img src="./images/logo.png" vite-ignore>

<!-- 동적 URL을 사용하는 경우 유용 -->
<img src="<%= dynamicImagePath %>" vite-ignore>

<!-- CDN 이미지 등 외부 리소스를 그대로 유지하고 싶을 때 -->
<img src="https://example.com/images/banner.jpg" vite-ignore>

 

postcss-load-config

postcss-load-config가 v4에서 v6으로 업데이트되었습니다. 이제 TypeScript postcss 설정 파일을 로드하기 위해 ts-node 대신 tsx 또는 jiti가 필요합니다. 또한 YAML postcss 설정 파일을 로드하기 위해 yaml이 필요합니다.

Sass가 이제 기본적으로 최신 API 사용

 

Vite 5에서는 Sass에 대해 기본적으로 레거시 API가 사용되었습니다. Vite 5.4에서 최신 API에 대한 지원이 추가되었습니다.

Vite 6부터는 Sass에 대해 기본적으로 최신 API가 사용됩니다. 여전히 레거시 API를 사용하고 싶다면 css.preprocessorOptions.sass.api: 'legacy' / css.preprocessorOptions.scss.api: 'legacy'로 설정할 수 있습니다. 그러나 레거시 API 지원은 Vite 7에서 제거될 예정입니다. 최신 API로 마이그레이션하려면 Sass 문서를 참조하세요.

라이브러리 모드에서 CSS 출력 파일 이름 사용자 정의

Vite 5에서는 라이브러리 모드의 CSS 출력 파일 이름이 항상 style.css였으며 Vite 설정을 통해 쉽게 변경할 수 없었습니다.

 

Vite 6부터는 기본 파일 이름이 JS 출력 파일과 유사하게 package.json의 "name"을 사용합니다. build.lib.fileName이 문자열로 설정된 경우, 해당 값도 CSS 출력 파일 이름에 사용됩니다. 다른 CSS 파일 이름을 명시적으로 설정하려면 새로운 build.lib.cssFileName을 사용하여 구성할 수 있습니다.

마이그레이션하려면, style.css 파일 이름에 의존했던 경우 패키지 이름을 기반으로 한 새 이름으로 참조를 업데이트해야 합니다. 예를 들어:

{
"name": "my-lib",
"exports": {
"./style.css": "./dist/my-lib.css"
}
}

 

Vite 5처럼 style.css를 유지하고 싶다면 대신 build.lib.cssFileName: 'style'로 설정할 수 있습니다.

---

 

출처 : https://vite.dev/guide/migration

Vite

이해 안가는 부분에 대한 내용을 추가하였으니 정확한 글은 원본을 확인해주세요.