Vite 6 환경 API가 가져온 멀티 런타임 변화와 사용법

Vite 6의 가장 핵심적인 아키텍처 변화는 환경 API 도입입니다. 프론트엔드 빌드 도구로 널리 쓰이던 Vite가 이제 브라우저와 Node.js를 넘어 다양한 자바스크립트 런타임을 정식으로 품기 시작했습니다.

왜 환경 API가 필요했을까

Vite 5까지는 내부 모듈 그래프가 브라우저용 클라이언트와 Node.js 기반 SSR이라는 두 가지 고정 환경만 전제하고 동작했습니다. 개발자가 Cloudflare Workers 같은 엣지 런타임이나 Bun, Deno 등 Node.js가 아닌 환경을 대상으로 코드를 실행하려면 여러 편법을 써야 했습니다. 개발 서버에서는 Node.js 모듈 흉내를 내다가 배포 직전에 번들러를 별도로 돌리는 방식이 대표적입니다.

이런 구조는 로컬 개발 환경과 실제 프로덕션 런타임 사이에 간극을 만들었습니다. 로컬에서는 잘 돌던 코드가 배포 후 엣지 환경의 내장 전역 객체 차이로 런타임 에러를 내거나, 모듈 교체인 HMR이 한쪽 런타임에서만 깨지는 문제가 반복되었습니다.

Vite 6 환경 API가 바꾼 구조

Vite 6는 환경이라는 개념을 일급 객체로 공식화했습니다. 이제 프레임워크나 플러그인 제작자가 필요에 따라 원하는 만큼 독립된 모듈 그래프와 런타임 환경을 선언할 수 있습니다.

클라이언트 웹 앱, Node.js 서버, Cloudflare Workers 실행 환경이 각자 다른 모듈 해석 규칙과 의존성 조건을 유지하면서도 하나의 Vite 개발 서버 안에서 통합 관리됩니다. 파일이 수정되면 연결된 모든 런타임 모듈 그래프가 즉시 업데이트를 공유받습니다.

다음은 Vite 6.0 기준 설정 파일에서 독립 환경을 정의하는 최소 구성입니다.

// Vite 6.0 기준: vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  environments: {
    client: {},
    ssr: {},
    edge: {
      resolve: {
        conditions: ['workerd', 'worker']
      }
    }
  }
})

각 환경은 자체 모듈 해석 조건을 가지므로 엣지 전용 패키지와 브라우저 전용 번들을 같은 프로젝트에서 충돌 없이 빌드할 수 있습니다.

언제 쓰고 언제 넘어가야 할까

일반적인 단일 페이지 애플리케이션(SPA)이나 전통적인 Node.js SSR 웹을 만드는 개발자라면 환경 API를 직접 작성할 필요가 없습니다. Vite 6는 기존 최상위 설정을 내부 client 및 ssr 환경으로 자동 연결하므로 기존 설정 그대로 업그레이드할 수 있습니다.

반면 Cloudflare Workers 플러그인을 결합한 풀스택 프로젝트를 구성하거나, 독자적인 서버 컴포넌트 프레임워크를 설계하는 팀이라면 이 API를 검토할 가치가 충분합니다. 개발 서버를 프로덕션 엣지 런타임과 일치시켜 배포 전 버그를 잡는 비용을 크게 줄여줍니다.

마루의 실무 시각

환경 API는 일반 애플리케이션 개발자에게 직접 노출되는 설정이라기보다 프레임워크와 에코시스템 플러그인을 단단하게 받치는 기반 공사입니다. 지금 당장 vite.config.ts를 재작성하기보다는, 프로젝트에서 사용하는 SSR 플러그인이나 엣지 어댑터가 Vite 6의 환경 API를 지원하는 버전으로 올라왔는지 확인하고 버전 업그레이드를 진행하는 편이 실용적입니다.

vivitejs

Vite 6 공식 발표 블로그

Vite 6 Release Announcement