Skip to content

Document the network hosts Vite+ contacts, for restricted environments #3533

Description

@hyunbinseo

Documentation is

  • Missing

Explain in Detail

I install Vite+ on a Linux machine with restricted outbound traffic. It has no private registry or mirror, but specific hosts can be allowed in the firewall. The docs don't list which hosts the installer, vp env, and the CLI contact.

#3296 and #3520 cover fully offline installs through mirrors. This is the online case with an allowlist.

Your Suggestion for Changes

A table of hosts with their purpose, when they're needed, and override variable. One-time hosts matter because their files can be copied in instead of allowed. From the source, I found:

Host Purpose Needed Override
vite.plus Install script First install Local copy
viteplus.dev Legacy installer fallback First install, if falling back VP_LEGACY_INSTALLER_URL
registry.npmjs.org CLI package, dependencies, pnpm Install, upgrade NPM_CONFIG_REGISTRY
nodejs.org Node.js (glibc) Install, new Node.js versions VP_NODE_DIST_MIRROR
unofficial-builds.nodejs.org Node.js (musl) Install, new Node.js versions VP_NODE_DIST_MIRROR
github.com Some vp create templates vp create, some templates

Is this complete and correct?

My goal is to allow only the hosts needed after the first install (e.g. registry.npmjs.org, nodejs.org), and copy everything else in once.

Relevant Page

https://viteplus.dev/guide/global-cli

Activity

  1. voidzero-bot commented on Nov 22, 2026

    @voidzero-bot
    Contributor
    • Reproduced: Yes — the consolidated host documentation is confirmed missing on current main, and the reporter's proposed table was verified against the source.
    • Exploration: Yes — View branch
    • Unit Test: No — documentation-only change; validated instead with a VitePress production build (dead-link check), anchor verification of the built HTML, vp fmt --check docs/, and git diff --check.
    • Priority: Priority P1: chore. This is a documentation gap with no user-facing behavior change — the underlying network contacts are intentional and the override variables already exist; only the documentation listing them is missing.

    The docs never consolidated the hosts the installers, vp env, and the CLI contact: docs/guide/global-cli.md documents the override variables (NPM_CONFIG_REGISTRY, VP_NODE_DIST_MIRROR) without naming the hosts they replace, and the installers' VP_LEGACY_INSTALLER_URL fallback (packages/cli/install.sh:54, install.ps1:47) was undocumented entirely. The reporter's table proved accurate, with a few additions found in source: setup.viteplus.dev (standalone Windows installer), the registry-bridge.viteplus.dev preview host, the Homebrew channel, and the fact that the built-in vite:library template requires github.com via degit.

    I found a potential fix for this issue. It adds a "Network Hosts" section to docs/guide/global-cli.md with install-time and runtime host tables (host / purpose / when needed / override), documents VP_LEGACY_INSTALLER_URL as an installation variable, and links the Node.js mirror section in docs/guide/env.md to the new section. Every host row is sourced from a code constant recorded in the report, so the suggestion just needs human review of wording and placement — note it may need a small merge-order resolution against open PR #3520, which covers the adjacent offline/mirror case.

    Full Triage Report

    Triage Report — Issue #3533: Document the network hosts Vite+ contacts, for restricted environments

    • Step: reproduce
    • Classification: Task (documentation request — no incorrect runtime behavior reported)
    • Result: Confirmed on current main — the documented gap exists, and the reporter's host table matches the source.

    Issue Summary

    The reporter installs Vite+ on a Linux machine with restricted outbound traffic (firewall allowlist, no private mirror). The docs do not list which hosts the installer, vp env, and the CLI contact, so they cannot build a complete allowlist or decide which one-time hosts can be satisfied by copying files in instead. They propose a host/purpose/needed/override table on the global CLI guide and ask whether their table is complete and correct.

    Relevant page: https://viteplus.dev/guide/global-cli (docs/guide/global-cli.md)

    Environment

    • Checkout: /home/runner/work/vite-plus/vite-plus (branch triagebot/fix-3533)
    • vp v1.7.0 (global CLI built from this checkout)
    • Node.js v24.22.3, pnpm v12.11.2
    • OS: Linux x64 (GitHub Actions runner)

    Verification Performed

    This is a documentation request, so "reproduction" means (a) confirming the missing documentation on the current checkout and (b) checking the reporter's proposed host table against the source.

    1. The documentation gap is real

    docs/guide/global-cli.md (the referenced page) documents install-time variables (NPM_CONFIG_REGISTRY, VP_NODE_DIST_MIRROR, VP_LEGACY_INSTALLER_URL is not documented there) and docs/guide/env.md documents the Node.js mirror, but:

    • grep -rn -i "firewall|allowlist|restricted environment|egress|outbound" docs/ returns only an unrelated line in docs/guide/create.md (Bingo --skip-requests).
    • There is no consolidated table of contacted hosts anywhere in docs/ — no page lists hosts, purpose, when needed, and override variables together.

    2. The reporter's host table matches the source

    Claimed host Verified in source Notes
    vite.plus docs/guide/global-cli.md:215 (curl -fsSL https://vite.plus | bash) Install script host; one-time on first install
    viteplus.dev packages/cli/install.sh:54 — LEGACY_INSTALLER_URL="${VP_LEGACY_INSTALLER_URL:-https://viteplus.dev/install-legacy.sh}" (same in install.ps1:47) Legacy installer fallback, used by installers on old shells / old vite-plus versions
    registry.npmjs.org crates/vp_pm_cli/src/config.rs:9 — DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org" Default for the CLI package, dependencies, and all four managed package managers (npm, pnpm, Yarn, and Bun via @oven/bun-{os}-{arch} npm packages, crates/vp_pm_cli/src/package_manager.rs:1947-1958; pnpm bootstrap also fetches from this registry, crates/vp_pm_cli/src/package_manager/bootstrap.rs). Override: NPM_CONFIG_REGISTRY / .npmrc
    nodejs.org crates/vp_js_runtime/src/providers/node.rs:22 — DEFAULT_NODE_DIST_URL = "https://nodejs.org/dist" (glibc) Override: VP_NODE_DIST_MIRROR
    unofficial-builds.nodejs.org same file, line 26 — musl fallback https://unofficial-builds.nodejs.org/download/release Override: VP_NODE_DIST_MIRROR
    github.com packages/cli/src/create/discovery.ts:14-27 — vp create treats https://github.com/... template names as remote repos Only for remote/custom templates; built-in templates do not need it

    So the table is accurate as far as it goes; github.com has no override variable (remote templates are user-supplied URLs).

    3. Hosts the reporter missed (observations for the diagnose/fix steps)

    • registry-bridge.viteplus.dev — used for preview installs (VP_PR_VERSION) and PR migrate previews; documented in docs/guide/upgrade.md:108 and docs/guide/migrate.md:135. Not needed for normal installs.
    • Homebrew install path (vp upgrade/install via Homebrew, crates/vp_global_cli/src/commands/upgrade/mod.rs:58, HomebrewFormula/vp.rb) contacts GitHub and Homebrew bottle hosts. Not relevant for the curl-installer path, but a host table should note the Homebrew variant.
    • vp env list-remote fetches Node.js and all four PM registry endpoints concurrently (docs/guide/env.md:214) — i.e. nodejs.org + the npm registry, not separate per-PM hosts.
    • Node.js release PGP keys are bundled in the binary (crates/vp_js_runtime/src/pgp_verify.rs), so no keyserver/GitHub fetch happens at runtime for verification.

    Commands Attempted

    • vp --version, node --version, pnpm --version — environment capture.
    • grep across docs/, crates/, packages/ for the claimed hosts and override variables; control check: searching the docs for consolidated host documentation returned nothing, confirming the gap rather than a misplaced section.

    Result

    Confirmed (reproduced): the requested documentation does not exist on current main, and the reporter's host list is accurate against the source, with the additions noted above. No runtime behavior to reproduce; classification is Task.


    Diagnosis (step: diagnose)

    Root Cause

    This is a documentation gap, not a code defect: no page in docs/ consolidates the network hosts the Vite+ installer, vp env, and the CLI contact. Mirror guidance exists but is scattered: docs/guide/global-cli.md documents NPM_CONFIG_REGISTRY and VP_NODE_DIST_MIRROR as variables without stating which hosts they replace or when each host is needed, and docs/guide/env.md#custom-node-js-mirror covers Node.js only. An operator building a firewall allowlist has to read the installers' source to get the list, which is exactly what the reporter did.

    The reporter's table is correct but incomplete for a fully allowlisted environment. Verified host inventory (all confirmed by direct source inspection on this checkout):

    One-time (first install; files can be copied in / allowed temporarily)

    Host Source of truth Purpose Override
    vite.plus docs/guide/global-cli.md:215 usage line; script header packages/cli/install.sh:3-6 Hosts the bootstrap shell/PowerShell script for curl -fsSL https://vite.plus | bash Fetch once, run a local copy of packages/cli/install.sh
    viteplus.dev packages/cli/install.sh:54, packages/cli/install.ps1:47 — LEGACY_INSTALLER_URL="${VP_LEGACY_INSTALLER_URL:-https://viteplus.dev/install-legacy.sh}" Legacy installer fallback when the modern script is unusable (old shells / old vite-plus versions); the modern script only fetches it when it falls back VP_LEGACY_INSTALLER_URL (including file://)
    registry.npmjs.org crates/vp_pm_cli/src/config.rs:9 (DEFAULT_NPM_REGISTRY); used by install.sh (metadata + platform tarball), crates/vp_installer/src/main.rs:130-146 (vp-setup resolve/download), and the pinned-pnpm bootstrap crates/vp_pm_cli/src/package_manager/bootstrap.rs Resolve and download the vite-plus CLI platform package; bootstrap the pinned pnpm used during setup NPM_CONFIG_REGISTRY / --registry / .npmrc
    nodejs.org crates/vp_js_runtime/src/providers/node.rs:22 (DEFAULT_NODE_DIST_URL = https://nodejs.org/dist), glibc branch Download Node.js when a system Node.js is absent or unusable VP_NODE_DIST_MIRROR
    unofficial-builds.nodejs.org same file line 26 (https://unofficial-builds.nodejs.org/download/release), musl branch Node.js musl builds on musl systems VP_NODE_DIST_MIRROR

    Recurring (needed after first install)

    Host Source of truth Purpose Override
    registry.npmjs.org crates/vp_pm_cli/src/package_manager.rs (npm tarball, @pnpm/* platform packages, @yarnpkg/cli-dist for Yarn 2+, @oven/bun-{os}-{arch} for Bun — lines 1947-1958, 2628; version lists via fetch_registry_versions) Project dependencies, vp install/add/publish, managed package-manager installs, vp dlx, npm-based vp create generators (e.g. create-vite@latest), vp upgrade (new CLI version), vp env list-remote PM version lists NPM_CONFIG_REGISTRY / .npmrc (project, user, and scope-level registries are honored)
    nodejs.org / unofficial-builds.nodejs.org crates/vp_js_runtime/src/providers/node.rs; docs/guide/env.md:214,311 vp env install/default, vp env list-remote (index.json), vp env exec provisioning a missing version VP_NODE_DIST_MIRROR
    github.com (+ codeload.github.com for tarballs; api.github.com for Bingo generators) packages/cli/src/create/discovery.ts:13-33 (GitHub URL templates → degit), packages/cli/src/create/templates/types.ts:1 + builtin.ts:31-50 (builtin vite:library template degits github:sxzz/tsdown-templates/vite-plus), docs/guide/create.md:214 (Bingo outbound GitHub API calls, skipped with --skip-requests) vp create with GitHub/remote templates — including the built-in library template, so github.com is not optional for all built-ins None (arbitrary user-supplied repo URLs; degit's cache can be seeded manually)

    Conditional / alternative channels worth documenting

    • registry-bridge.viteplus.dev — only for preview installs (VP_PR_VERSION, packages/cli/install.sh:43-44; crates/vp_global_cli/src/self_setup.rs:241; docs/guide/upgrade.md:108, docs/guide/migrate.md:135).
    • Homebrew channel (brew tap voidzero-dev/vite-plus, crates/vp_global_cli/src/commands/upgrade/mod.rs:58; HomebrewFormula/vp.rb) — contacts GitHub and Homebrew bottle hosts instead of the npm registry for the CLI itself. The curl-installer allowlist does not cover this path.

    Things that do not need to be allowed (dispel concerns)

    • No keyserver or GitHub fetch for Node.js signature verification: the release PGP keys are bundled in the binary (crates/vp_js_runtime/src/pgp_verify.rs:49).
    • No per-PM download hosts (yarnpkg.com, bun.sh): all four managed package managers come from the npm registry (or NPM_CONFIG_REGISTRY).
    • viteplus.dev URLs in the binary are documentation links only.

    Why This Causes the Observed Behavior

    The reporter's goal — "allow only the hosts needed after the first install and copy everything else in once" — cannot be achieved from the docs alone, because (a) no page states which hosts are one-time versus recurring, (b) VP_LEGACY_INSTALLER_URL and the vite.plus bootstrap origin are not documented at all (the fallback host appears nowhere in docs/), and (c) the GitHub requirement of the built-in vite:library template is non-obvious.

    Suggested Fix Approach

    Add a "Network access" (allowlist) section to docs/guide/global-cli.md, linked from docs/guide/env.md and possibly docs/guide/create.md:

    1. A table in the reporter's format (host / purpose / when needed / override), split into one-time install hosts and recurring runtime hosts, using the verified inventory above.
    2. A short "one-time hosts" subsection noting that vite.plus and the legacy installer fallback can be satisfied by copying packages/cli/install.sh in (with VP_LOCAL_TGZ/VP_LOCAL_BINARY noted for fully local installs).
    3. Notes for the edge cases: registry-bridge.viteplus.dev only for previews, the Homebrew channel, the bundled PGP keys (no keyserver), and all PMs resolving through the single npm registry variable.
    4. Cross-link the existing mirror sections (/guide/global-cli#npm-config-registry, /guide/env#custom-node-js-mirror) instead of duplicating them, and mention Document installing and running Vite+ on machines with no internet access #3296/docs(ci): document offline installs with a private registry #3520 for the fully offline mirror case.

    Documentation-only change: validate with git diff --check and a link/anchor check per AGENTS.md ("Documentation / agent guidance" row); no code, snapshot, or unit tests affected.

    Edge Cases for the Fix

    • The musl vs glibc Node.js split: one mirror variable (VP_NODE_DIST_MIRROR) covers both hosts, but the host column must show both.
    • github.com templates accept arbitrary repos and vp dlx accepts arbitrary packages, so an allowlist can only cover the built-in/blessed paths; the doc should say so.
    • Keep host claims sourced from code constants so the table stays accurate if origins change (e.g. DEFAULT_NODE_DIST_URL, DEFAULT_NPM_REGISTRY, LEGACY_INSTALLER_URL).

    Confidence

    high — every host and override was verified by reading the exact constants and call sites in the current checkout; the missing-documentation conclusion is confirmed by exhaustive grep over docs/. No behavior is inferred.


    Verification (step: verify)

    Claim

    • Observed: The Vite+ installers, vp env, and CLI commands contact several network hosts, and the shipped documentation never lists them. An operator with an outbound-traffic allowlist cannot determine which hosts to permit, or which one-time hosts can be satisfied by copying files in instead.
    • Expected: A consolidated host table (host / purpose / when needed / override variable) on the global CLI guide, covering both install-time and runtime hosts.

    Research Performed

    Network behavior is intentional and override-aware

    The host contacts are deliberate features with designed override variables (verified in the diagnose step): NPM_CONFIG_REGISTRY (crates/vp_pm_cli/src/config.rs:9, documented in docs/guide/global-cli.md), VP_NODE_DIST_MIRROR (crates/vp_js_runtime/src/providers/node.rs:22,26, documented in docs/guide/env.md#custom-node-js-mirror), and VP_LEGACY_INSTALLER_URL (packages/cli/install.sh:54, install.ps1:47 — not documented anywhere). Nothing in the docs contradicts the observed network behavior, so there is no behavioral defect.

    No previous host table was removed (not a regression)

    git log --all -S "registry.npmjs.org" -- docs/ and -S "unofficial-builds" -- docs/ show the hosts appear only as example URLs or defaults inside variable documentation; no consolidated host table ever existed and was removed. The gap is a longstanding omission, not a regression.

    The project is actively documenting this area

    Verdict

    bug — in the documentation sense: the host documentation is genuinely missing and nothing shows the omission was intentional. The underlying network behavior itself is intended (no behavioral change needed), but the missing allowlist documentation is a real defect the project has accepted as actionable ("contribution welcome"). PR #3520 solves the adjacent offline/mirror case and does not cover this issue's online-allowlist case, so #3533 is not a duplicate of it.

    Confidence: high — direct evidence: exhaustive grep of docs/ (no host table, current HEAD), git history (no table ever removed), GitHub state (#3533 labeled documentation, contribution welcome; #3296/#3520 open and adjacent but not overlapping), and source-verified host inventory from the reproduce/diagnose steps.

    Note for the fix step: a fix should merge cleanly alongside #3520 — that PR rewrites the "Development variables" section and adds "Install from private mirrors" to docs/guide/global-cli.md, so the new host table should either link into that section or land after #3520 to avoid conflicts.


    Fix (step: fix)

    Decision to Fix

    Changed Files

    1. docs/guide/global-cli.md
      • New #### \VP_LEGACY_INSTALLER_URL`entry under Installation Variables (the variable was referenced by the install scripts —packages/cli/install.sh:54, install.ps1:47` — but previously undocumented).
      • New ## Network Hosts section after the Homebrew section, with:
        • an install-time host table (vite.plus, setup.viteplus.dev, viteplus.dev, registry.npmjs.org, nodejs.org, unofficial-builds.nodejs.org) including purpose, when needed, and override;
        • a runtime host table (registry.npmjs.org, nodejs.org/unofficial-builds.nodejs.org, github.com for vp create templates);
        • notes for the conditional hosts (registry-bridge.viteplus.dev for VP_PR_VERSION previews, Homebrew's GitHub Releases channel), the absence of keyserver traffic (bundled Node.js release keys), the Bingo --skip-requests behavior, and pointers to the existing mirror documentation (NPM_CONFIG_REGISTRY, /guide/env#custom-node-js-mirror).
    2. docs/guide/env.md
      • One pointer sentence from "Custom Node.js Mirror" to the new Network Hosts section.

    Rationale

    The reporter's proposed table was correct and this fix adopts it, with the additions verified from source: setup.viteplus.dev (standalone Windows installer), the preview-bridge host, the Homebrew channel, and the note that the built-in vite:library template needs github.com (via degit) — plus the undocumented VP_LEGACY_INSTALLER_URL variable documentation the table references. No host claim is un-sourced: every row maps to a constant or call site recorded in the diagnose step.

    Regression Test

    Documentation-only change: no unit test applies (per AGENTS.md, documentation changes are validated with link/reference verification instead). The VitePress production build acts as the regression check — it fails on dead links and renders every anchor referenced from the new section:

    • id="network-hosts", id="vp-legacy-installer-url", id="installation-variables", id="runtime-variables", id="vp-pr-version", id="homebrew", id="npm-config-registry", id="vp-node-dist-mirror" all resolve in docs/.vitepress/dist/guide/global-cli.html.
    • The cross-page link /guide/global-cli#network-hosts from env.md resolves.

    Validation Commands and Results

    Command Result
    git diff --check -- docs/guide/global-cli.md docs/guide/env.md clean
    vp fmt --check docs/ "All matched files use the correct format." (initially failed on my unformatted table; fixed with vp fmt docs/guide/global-cli.md)
    cd docs && pnpm build (VitePress production build incl. dead-link check) "build complete in 10.38s"
    Anchor verification against built HTML all 8 in-page anchors + 1 cross-page link resolve
    Referenced files/URLs (install-legacy.sh, install-legacy.ps1, setup.viteplus.dev per existing docs line 72) verified present

    Skipped: vp check, pnpm test:unit, Rust checks — no TypeScript/Rust code changed (docs-only diff). Skipped: full pnpm test — not applicable to a documentation change per AGENTS.md ("Documentation-only changes need no unrelated test suites").

    Notes for the Maintainer

    This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

    I've opened a pull request with this fix: #3534

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    Fields

    Priority

    None yet

    Effort

    None yet

    Target date

    None yet

    Start date

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions