10 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / Vite — Getting Started, Features & Env Variables and Modes | official-doc | https://vite.dev/guide/ |
|
|
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]우선순위 등 세부 메커니즘의 전체 규칙 (본 인용에는 요약만 포함, 전체 규칙은 원문 § ".envFiles" 참조)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
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/...]](생성 시 추가)