Skip to content

Commit c631dd0

Browse files
fengmk2fengmk2
committed
docs(rfc): restructure Installation Flow with visual diagram
Replace the flat numbered list with a phased ASCII diagram grouped into Resolve, Download & Verify, Install, Activate, and Configure phases. Add a function-to-crate mapping table and document the failure recovery boundary (pre/post Activate phase). Annotate conditional steps (save_previous_version only on upgrade, modify PATH gated by --no-modify-path).
1 parent 4ed6f0e commit c631dd0

File tree

1 file changed

+96
-47
lines changed

1 file changed

+96
-47
lines changed

‎rfcs/windows-installer.md‎

Lines changed: 96 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -202,57 +202,106 @@ CLI flags take precedence over environment variables.
202202

203203
## Installation Flow
204204

205-
The installer performs the exact same steps as `install.ps1`, in Rust:
205+
The installer replicates the same result as `install.ps1`, implemented in Rust via `vite_setup`.
206206

207207
```
208-
1. Detect platform → vite_setup::platform::detect_platform_suffix()
209-
(win32-x64-msvc or win32-arm64-msvc)
210-
211-
2. Resolve version → vite_setup::registry::resolve_version()
212-
Query npm registry for latest/specified version
213-
214-
3. Check existing install → Read %VP_HOME%\current target, compare versions
215-
Skip if already at target version
216-
217-
4. Download tarball → vite_install::HttpClient::get_bytes()
218-
With progress bar via indicatif
219-
220-
5. Verify integrity → vite_setup::integrity::verify_integrity()
221-
SHA-512 SRI hash from npm metadata
222-
223-
6. Create version dir → %VP_HOME%\{version}\bin\
224-
225-
7. Extract binary → vite_setup::extract::extract_platform_package()
226-
Extracts vp.exe and vp-shim.exe
227-
228-
8. Generate package.json → vite_setup::package_json::generate()
229-
Wrapper package.json in version dir
230-
231-
9. Write .npmrc → vite_setup::npmrc::write_release_age_overrides()
232-
minimum-release-age=0
233-
234-
10. Install deps → Spawn: {version_dir}\bin\vp.exe install --silent
235-
236-
11. Swap current junction → vite_setup::link::swap_current_link()
237-
mklink /J current → {version}
238-
239-
12. Create bin shims → Copy vp-shim.exe → %VP_HOME%\bin\vp.exe
240-
241-
13. Setup Node.js manager → Prompt or auto-detect, then:
242-
Spawn: vp.exe env setup --refresh
243-
244-
14. Cleanup old versions → vite_setup::cleanup::cleanup_old_versions()
245-
Keep last 5
246-
247-
15. Modify User PATH → Registry: HKCU\Environment\Path
248-
Add %VP_HOME%\bin if not present
249-
Broadcast WM_SETTINGCHANGE
250-
251-
16. Create env files → Spawn: vp.exe env setup --env-only
252-
253-
17. Print success → Show getting-started commands
208+
┌─────────────────────────────────────────────────────────────┐
209+
│ RESOLVE │
210+
│ │
211+
│ ┌─ detect platform ──────── win32-x64-msvc │
212+
│ │ win32-arm64-msvc │
213+
│ │ │
214+
│ ├─ resolve version ──────── query npm registry │
215+
│ │ "latest" → "0.3.0" │
216+
│ │ │
217+
│ └─ check existing ──────── read %VP_HOME%\current │
218+
│ same version? → exit early │
219+
└─────────────────────────────────────────────────────────────┘
220+
│
221+
▼
222+
┌─────────────────────────────────────────────────────────────┐
223+
│ DOWNLOAD & VERIFY │
224+
│ │
225+
│ ┌─ download tarball ─────── GET tarball URL from registry │
226+
│ │ progress spinner via indicatif │
227+
│ │ │
228+
│ └─ verify integrity ─────── SHA-512 SRI hash comparison │
229+
└─────────────────────────────────────────────────────────────┘
230+
│
231+
▼
232+
┌─────────────────────────────────────────────────────────────┐
233+
│ INSTALL │
234+
│ │
235+
│ ┌─ extract binary ──────── %VP_HOME%\{version}\bin\ │
236+
│ │ vp.exe + vp-shim.exe │
237+
│ │ │
238+
│ ├─ generate package.json ─ wrapper with vite-plus dep │
239+
│ │ pins pnpm@10.33.0 │
240+
│ │ │
241+
│ ├─ write .npmrc ────────── minimum-release-age=0 │
242+
│ │ │
243+
│ └─ install deps ────────── spawn: vp install --silent │
244+
│ installs vite-plus + transitive │
245+
└─────────────────────────────────────────────────────────────┘
246+
│
247+
▼
248+
┌─────────────────────────────────────────────────────────────┐
249+
│ ACTIVATE ◄── point of no │
250+
│ return │
251+
│ ┌─ save previous version ── .previous-version (rollback) │
252+
│ │ (only if upgrading existing) │
253+
│ │ │
254+
│ └─ swap current ───────���── mklink /J current → {version} │
255+
│ (junction on Windows, │
256+
│ atomic symlink on Unix) │
257+
└─────────────────────────────────────────────────────────────┘
258+
│
259+
▼
260+
┌─────────────────────────────────────────────────────────────┐
261+
│ CONFIGURE │
262+
│ │
263+
│ ┌─ create bin shims ────── copy vp-shim.exe → bin\vp.exe │
264+
│ │ (rename-to-.old if running) │
265+
│ │ │
266+
│ ├─ Node.js manager ────── if enabled: │
267+
│ │ spawn: vp env setup --refresh │
268+
│ │ if disabled: │
269+
│ │ spawn: vp env setup --env-only │
270+
│ │ │
271+
│ ├─ cleanup old versions ── keep last 5 by creation time │
272+
│ │ (non-fatal on error) │
273+
│ │ │
274+
│ └─ modify User PATH ────── if --no-modify-path not set: │
275+
│ HKCU\Environment\Path │
276+
│ prepend %VP_HOME%\bin ���
277+
│ broadcast WM_SETTINGCHANGE │
278+
└─────────────────────────────────────────────────────────────┘
279+
│
280+
▼
281+
✔ Print success
254282
```
255283

284+
Each phase maps to `vite_setup` library functions shared with `vp upgrade`:
285+
286+
| Phase | Key function | Crate |
287+
| ----------------- | ------------------------------------------ | ---------------- |
288+
| Resolve | `platform::detect_platform_suffix()` | `vite_setup` |
289+
| Resolve | `registry::resolve_version()` | `vite_setup` |
290+
| Resolve | `install::read_current_version()` | `vite_setup` |
291+
| Download & Verify | `HttpClient::get_bytes()` | `vite_install` |
292+
| Download & Verify | `integrity::verify_integrity()` | `vite_setup` |
293+
| Install | `install::extract_platform_package()` | `vite_setup` |
294+
| Install | `install::generate_wrapper_package_json()` | `vite_setup` |
295+
| Install | `install::write_release_age_overrides()` | `vite_setup` |
296+
| Install | `install::install_production_deps()` | `vite_setup` |
297+
| Activate | `install::save_previous_version()` | `vite_setup` |
298+
| Activate | `install::swap_current_link()` | `vite_setup` |
299+
| Configure | `install::refresh_shims()` | `vite_setup` |
300+
| Configure | `install::cleanup_old_versions()` | `vite_setup` |
301+
| Configure | `windows_path::add_to_user_path()` | `vite_installer` |
302+
303+
On failure before the **Activate** phase, the version directory is cleaned up and the existing installation remains untouched. After the **Activate** phase (junction swap), the update has already succeeded — subsequent configure steps are best-effort (non-fatal on error).
304+
256305
## Windows-Specific Details
257306

258307
### PATH Modification via Registry

0 commit comments

Comments
 (0)