86 lines
10 KiB
Markdown
86 lines
10 KiB
Markdown
---
|
|
title: official-doc / Vite — Getting Started, Features & Env Variables and Modes
|
|
source_type: official-doc
|
|
url: https://vite.dev/guide/
|
|
archive_url:
|
|
related_branches: []
|
|
related_projects: [ca-skeleton-frontend]
|
|
tags: [official-doc, ca-skeleton, frontend, javascript, react]
|
|
created: 2026-07-18
|
|
---
|
|
|
|
# official-doc / Vite — Getting Started, Features & Env Variables and Modes
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
|
|
## source_type 허용값
|
|
|
|
`official-doc` — Vite 는 VoidZero Inc. 가 운영하는 공식 프로젝트 문서(`vite.dev`). 벤더 공식 문서로 취급.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
> foundational 조사 — 특정 branch 없이 프로젝트 초기 도구 선택(dev server / build tool / env-config 계약)의 근거로 수집.
|
|
|
|
| Parent | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | client-only React SPA skeleton 에서 Vite 를 dev server + build tool 로 선택하는 근거 — native ESM 기반 dev server, 정적 자산 프로덕션 빌드, 그리고 `VITE_` prefix 기반 env-config 계약(클라이언트 번들에 비밀값 노출 금지)의 공식 근거 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://vite.dev/guide/ (Getting Started), https://vite.dev/guide/features (Features), https://vite.dev/guide/env-and-mode.html (Env Variables and Modes)
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: VoidZero Inc. and Vite contributors
|
|
- 발행일: 상시 갱신 문서 (버전 v8.1.5 기준, 페이지 footer `© 2019-present VoidZero Inc. and Vite contributors.`)
|
|
- 마지막 확인일: 2026-07-18
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
client-only React SPA skeleton(`ca-skeleton-frontend`)의 dev server / production build 도구로 Vite 를 선택하는 결정, 그리고 그 위에 얹을 env-config 계약(`VITE_` prefix 만 클라이언트 노출, 나머지는 서버 전용)의 공식 근거를 확보하기 위해 보관. 특히 "클라이언트 번들에 비밀값을 넣지 않는다"는 규칙은 본 자료가 직접 명시한 공식 경고이므로 branch 결정의 1차 근거로 인용 가능.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [Getting Started § Overview] "A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR)."
|
|
|
|
> [Getting Started § Overview] "A build command that bundles your code with Rolldown, pre-configured to output highly optimized static assets for production."
|
|
|
|
> [Env Variables and Modes § 도입부] "Vite exposes certain constants under the special import.meta.env object. These constants are defined as global variables during dev and statically replaced at build time to make tree-shaking effective."
|
|
|
|
> [Env Variables and Modes § Env Variables] "Variables prefixed with VITE_ will be exposed in client-side source code after Vite bundling. To prevent accidentally leaking env variables to the client, avoid using this prefix."
|
|
|
|
> [Env Variables and Modes § Env Variables → "Protecting secrets"] "VITE_* variables should not contain sensitive information such as API keys. The values of these variables are bundled into your source code at build time. For production deployments, consider a backend server or serverless/edge functions to properly secure secrets."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| VITE-C1 | Vite dev server 는 native ES modules 위에 기능(예: 빠른 HMR)을 얹는 방식으로 동작한다 | [Getting Started] "A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR)." | `official-vendor-doc` | "왜 Vite dev server 인가" — no-bundle-in-dev 아키텍처 근거 | HMR 속도가 다른 도구 대비 얼마나 빠른지 수치 비교는 증명 안 함 (벤치마크 없음) |
|
|
| VITE-C2 | Vite 의 production build 는 Rolldown 으로 코드를 번들링해 최적화된 정적 자산을 산출한다 | [Getting Started] "A build command that bundles your code with Rolldown, pre-configured to output highly optimized static assets for production." | `official-vendor-doc` | client-only SPA 를 정적 호스팅으로 배포하는 근거 (static asset output) | Rolldown 이 Rollup/webpack/esbuild 대비 항상 더 작은/빠른 번들을 만든다는 비교 증명은 아님. **주의: 현재 공식 문서(v8.1.5)는 "Rollup" 이 아니라 "Rolldown" 을 명시 — 아래 메모 참조** |
|
|
| VITE-C3 | `import.meta.env` 의 상수들은 dev 중엔 전역 변수로 정의되고, build 시점엔 정적으로 치환되어 tree-shaking 이 유효하게 동작한다 | [Env Variables and Modes] "Vite exposes certain constants under the special import.meta.env object. These constants are defined as global variables during dev and statically replaced at build time to make tree-shaking effective." | `official-vendor-doc` | env-config 접근이 런타임 fetch 가 아니라 build-time 정적 치환이라는 전제의 근거 | 환경마다 다른 값을 쓰려면 재빌드가 필요하다는 결론까지 직접 진술하지는 않음 (정적 치환이라는 사실에서 도출되는 추론) |
|
|
| VITE-C4 | `VITE_` prefix 가 붙은 변수만 Vite 번들링 후 클라이언트 소스코드에 노출되고, prefix 없는 변수는 노출되지 않는다(우연한 유출 방지를 위해 이 prefix 를 신중히 사용하라 경고) | [Env Variables and Modes] "Variables prefixed with VITE_ will be exposed in client-side source code after Vite bundling. To prevent accidentally leaking env variables to the client, avoid using this prefix." | `official-vendor-doc` | env-config 계약의 "무엇을 `VITE_` prefix 로 노출할지" 경계 규칙의 1차 근거 | `envPrefix` 커스터마이징 시의 세부 동작까지 다루지 않음(다른 옵션 페이지 참조 지시만 있음). 로그·디버그 출력 등 다른 경로를 통한 우발적 유출까지 커버한다고 증명하지 않음 |
|
|
| VITE-C5 | `VITE_*` 변수는 build 시점에 소스코드에 번들링되므로 API 키 같은 민감정보를 담으면 안 되며, 프로덕션에서 비밀을 지키려면 백엔드 서버 또는 서버리스/엣지 함수를 고려하라 | [Env Variables and Modes → "Protecting secrets"] "VITE_* variables should not contain sensitive information such as API keys. The values of these variables are bundled into your source code at build time. For production deployments, consider a backend server or serverless/edge functions to properly secure secrets." | `official-vendor-doc` | "클라이언트 번들에 비밀값 금지" 규칙 그 자체의 공식 근거 — env-config 계약의 핵심 문장 | 이 프로젝트(`ca-skeleton-frontend`)가 실제로 백엔드/서버리스 프록시를 어떻게 구현해야 하는지는 규정하지 않음 (일반 권고만 제시, 구체 아키텍처는 별도 branch 결정 사항) |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `VITE-C1`, `VITE-C2`: Vite 의 dev server(native ESM 기반) / production build(Rolldown 기반) 아키텍처 자체
|
|
- `VITE-C3`, `VITE-C4`, `VITE-C5`: `import.meta.env` 의 build-time 정적 치환 특성, `VITE_` prefix 가 클라이언트 노출 경계선이라는 것, 그리고 비밀값을 `VITE_*` 에 넣지 말라는 공식 경고
|
|
- 이 자료가 증명하지 않는 것:
|
|
- Vite 가 다른 빌드 도구(webpack, esbuild 단독, Parcel 등) 대비 "더 낫다"는 비교 우위 — 이 문서는 Vite 의 동작 방식만 서술, 비교 벤치마크 없음
|
|
- `ca-skeleton-frontend` 의 실제 배포 환경(정적 호스팅 vs 서버 렌더링 등)에서 이 동작이 그대로 재현된다는 것 — 로컬/실제 빌드 검증 필요
|
|
- `envPrefix` 커스터마이징, `.env.[mode]` 우선순위 등 세부 메커니즘의 전체 규칙 (본 인용에는 요약만 포함, 전체 규칙은 원문 § "`.env` Files" 참조)
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- `ca-skeleton-frontend` 실제 `vite.config.*` 및 `.env*` 파일에서 `VITE_` prefix 규칙이 실제로 준수되는지 (코드 검증 필요 — 이 raw 문서만으로는 `actually-implemented` 등급 부여 불가)
|
|
- 비밀값을 다루는 백엔드/서버리스 프록시 패턴의 구체 설계는 본 문서 범위 밖 — 별도 branch 결정 필요
|
|
|
|
## 메모 / Notes
|
|
|
|
- **중요 불일치 플래그**: 조사 요청 시 "production build (Rollup)" 이라 언급되었으나, 2026-07-18 확인 시점의 공식 문서(v8.1.5, `vite.dev`)는 프로덕션 번들러로 **"Rollup" 이 아니라 "Rolldown"** 을 명시함 (`build.rolldownOptions`, `rolldown.rs` 링크 등 다수 확인). Vite 는 "Rolldown-powered Vite" 전환으로 기본 번들러가 Rollup → Rolldown(Rust 기반 Rollup 호환 번들러)으로 바뀐 것으로 보임. 과거 버전(Vite ≤6) 공식 문서에는 Rollup 이 프로덕션 번들러로 명시되어 있었을 가능성이 높으나, 본 raw 문서는 **현재 시점 원문 그대로**(Rolldown)를 인용했다. branch-note 등 후속 문서에서 "Vite = Rollup 기반"이라고 쓰면 이 시점 기준으로는 부정확하므로 주의.
|
|
- dev 서버 pre-bundling 도 esbuild 가 아니라 Rolldown 으로 수행된다고 Features 페이지에 명시됨 ("The pre-bundling step is performed with Rolldown") — 이 또한 과거(esbuild 시절) 문서와 달라진 부분으로 추정, 별도 확인 필요.
|
|
- Features 페이지에는 React Fast Refresh 가 Vite 의 first-party HMR 통합으로 언급됨 — `ca-skeleton-frontend` 가 React 기반이므로 관련성 있으나, 이 raw 문서에서는 quote 로 채택하지 않음(핵심 5개 인용에 포함 안 함, 필요 시 별도 인용 추가 가능).
|
|
- 인용 5개 모두 self-grep 통과 (아래 검증 참조).
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: (아직 없음 — Vite 관련 첫 raw 자료)
|
|
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시 추가)
|