From 3a95df99165ea24d4280fd114b6155f06adbef8c Mon Sep 17 00:00:00 2001
From: leihaohao <leihaohao@neucloud.cn>
Date: Wed, 24 Jun 2026 17:39:34 +0800
Subject: [PATCH] feat(passthrough): add low-Node passthrough for eligible
 commands

Closes #1909
Closes #1916

When the project's resolved Node version is below the supported minimum
(20.19.0), eligible commands (vp run/vpr + package-manager family) bypass
the Vite+ JS CLI and run the project's package manager directly.

- Add shared passthrough module (vite_shared) with version comparison
- Add passthrough command routing (vite_global_cli) with PATH handling
- Add dispatch_with_pm for externally-provided PackageManager
- Add detect_only on PackageManagerBuilder (no devEngines pin)
- Defer is_low_node check in vpx until actually needed
- Use vite_shared path utilities for safe non-UTF-8 PATH handling
---
 Cargo.lock                                    |   2 +
 crates/vite_global_cli/src/cli.rs             |  13 +
 crates/vite_global_cli/src/commands/mod.rs    |   3 +
 .../src/commands/passthrough.rs               | 336 ++++++++++++++++++
 crates/vite_global_cli/src/commands/vpr.rs    |  46 +++
 crates/vite_global_cli/src/commands/vpx.rs    | 106 +++++-
 .../vite_global_cli/tests/passthrough_e2e.rs  |  65 ++++
 crates/vite_install/src/package_manager.rs    | 140 ++++++++
 crates/vite_pm_cli/Cargo.toml                 |   3 +
 crates/vite_pm_cli/src/dispatch.rs            |  51 ++-
 crates/vite_pm_cli/src/handlers.rs            | 229 +++++++++++-
 crates/vite_shared/Cargo.toml                 |   1 +
 crates/vite_shared/src/lib.rs                 |   2 +
 crates/vite_shared/src/passthrough.rs         | 120 +++++++
 .../passthrough-notice/.node-version          |   1 +
 .../passthrough-notice/package.json           |   7 +
 .../passthrough-notice/snap.txt               |   4 +
 .../passthrough-notice/steps.json             |   5 +
 18 files changed, 1113 insertions(+), 21 deletions(-)
 create mode 100644 crates/vite_global_cli/src/commands/passthrough.rs
 create mode 100644 crates/vite_global_cli/tests/passthrough_e2e.rs
 create mode 100644 crates/vite_shared/src/passthrough.rs
 create mode 100644 packages/cli/snap-tests-global/passthrough-notice/.node-version
 create mode 100644 packages/cli/snap-tests-global/passthrough-notice/package.json
 create mode 100644 packages/cli/snap-tests-global/passthrough-notice/snap.txt
 create mode 100644 packages/cli/snap-tests-global/passthrough-notice/steps.json

diff --git a/Cargo.lock b/Cargo.lock
index d1e34dc7d6..a3cd4d9d38 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8504,6 +8504,7 @@ version = "0.0.0"
 dependencies = [
  "clap",
  "serde_json",
+ "tempfile",
  "thiserror 2.0.18",
  "tokio",
  "tracing",
@@ -8563,6 +8564,7 @@ version = "0.0.0"
 dependencies = [
  "directories",
  "nix 0.30.1",
+ "node-semver",
  "owo-colors",
  "reqwest",
  "rustls",
diff --git a/crates/vite_global_cli/src/cli.rs b/crates/vite_global_cli/src/cli.rs
index 93d363ff82..a4d1159e43 100644
--- a/crates/vite_global_cli/src/cli.rs
+++ b/crates/vite_global_cli/src/cli.rs
@@ -901,6 +901,19 @@ pub async fn run_command_with_options(
         return Ok(std::process::ExitStatus::default());
     };
 
+    // Low-Node passthrough precheck: when the project's resolved Node is below
+    // the supported minimum AND the command is eligible (run / package manager),
+    // bypass the Vite+ JS CLI and run the project's own package manager directly.
+    if commands::passthrough::is_eligible(&command) {
+        if let Some(node_version) = commands::passthrough::resolve_project_node_version(&cwd).await {
+            if commands::passthrough::should_passthrough(&command, &node_version) {
+                let mut executor = crate::js_executor::JsExecutor::new(None);
+                let runtime = executor.ensure_project_runtime(&cwd).await?;
+                return commands::passthrough::execute(&cwd, &command, runtime).await;
+            }
+        }
+    }
+
     match command {
         // Category A: Package Manager Commands
         // Print the runtime header for `vp install` (when not silent).
diff --git a/crates/vite_global_cli/src/commands/mod.rs b/crates/vite_global_cli/src/commands/mod.rs
index 18679f0de6..09c2f701de 100644
--- a/crates/vite_global_cli/src/commands/mod.rs
+++ b/crates/vite_global_cli/src/commands/mod.rs
@@ -110,6 +110,9 @@ pub mod upgrade;
 // Category C: Local CLI Delegation
 pub mod delegate;
 
+// Low-Node passthrough (degrades eligible commands to the project's package manager)
+pub mod passthrough;
+
 #[cfg(test)]
 mod tests {
     use vite_path::AbsolutePathBuf;
diff --git a/crates/vite_global_cli/src/commands/passthrough.rs b/crates/vite_global_cli/src/commands/passthrough.rs
new file mode 100644
index 0000000000..f52f7eff50
--- /dev/null
+++ b/crates/vite_global_cli/src/commands/passthrough.rs
@@ -0,0 +1,336 @@
+//! Low-Node passthrough: when the project's Node is below the supported
+//! minimum, eligible commands (`vpr`/`vp run` + the package-manager family)
+//! bypass the Vite+ JS CLI and run the project's own package manager directly,
+//! skipping `devEngines` pinning.
+
+use std::{collections::HashMap, process::ExitStatus};
+
+use vite_command::run_command;
+use vite_install::PackageManager;
+use vite_js_runtime::JsRuntime;
+use vite_path::AbsolutePath;
+use vite_shared::{PrependOptions, is_node_below_min, prepend_to_path_env};
+
+use crate::{cli::Commands, error::Error};
+
+/// Commands that degrade to passthrough on low Node.
+///
+/// Add new commands here ONLY if they are pure script-run / package-manager
+/// operations. Dev/build/test/lint/fmt/check/pack depend on bundled tools and
+/// are NEVER eligible.
+///
+/// Global PM operations (`-g`/`--global`) are excluded because they should use
+/// VP's managed global install system, which has its own Node runtime.
+#[allow(dead_code)] // called by run_command_with_options and execute_vpr
+#[must_use]
+pub fn is_eligible(command: &Commands) -> bool {
+    match command {
+        Commands::Run { .. } => true,
+        Commands::PackageManager(pm_cmd) => !is_global_pm_command(pm_cmd),
+        _ => false,
+    }
+}
+
+/// Returns true if the PM command is a global operation that should bypass
+/// passthrough and use VP's managed install system instead.
+///
+/// Mirrors [`PackageManagerCommand::is_managed_global`] — keep in sync.
+fn is_global_pm_command(command: &vite_pm_cli::PackageManagerCommand) -> bool {
+    command.is_managed_global()
+}
+
+/// Print the one-line passthrough notice. Pure I/O, no version check.
+pub(crate) fn print_passthrough_notice(node_version: &str, min: &str) {
+    // Reuse shared output style; keep to a single concise line.
+    vite_shared::output::warn(&format!(
+        "Node {node_version} is below the Vite+ minimum ({min}); using passthrough mode — \
+         running the project's package manager directly without loading the Vite+ CLI. \
+         Upgrade Node to restore full Vite+ functionality."
+    ));
+}
+
+/// Returns true when passthrough should activate: eligible command AND the
+/// resolved Node version is below the supported minimum.
+#[allow(dead_code)] // called by run_command_with_options and execute_vpr
+#[must_use]
+pub fn should_passthrough(command: &Commands, node_version: &str) -> bool {
+    is_eligible(command) && is_node_below_min(node_version)
+}
+
+/// Run an eligible command in passthrough mode.
+///
+/// `runtime` is the resolved project Node (already ensured/downloaded by the
+/// precheck caller in `run_command_with_options`). The package manager is
+/// resolved via `PackageManager::detect_only` (no `devEngines` pin):
+/// - `Commands::PackageManager` delegates to `vite_pm_cli::dispatch_with_pm`,
+///   reusing the existing `resolve_*` parameter generation (zero drift).
+/// - `Commands::Run` (`vpr`/`vp run <script>`) builds `<pm> run <script>` via
+///   `resolve_install_command` and executes it directly (nr-style).
+///
+/// The Node runtime bin is prepended to PATH so the pm shim resolves node.
+#[allow(dead_code)] // called by run_command_with_options and execute_vpr
+pub async fn execute(
+    cwd: &AbsolutePath,
+    command: &Commands,
+    runtime: &JsRuntime,
+) -> Result<ExitStatus, Error> {
+    let node_version = runtime.version();
+    print_passthrough_notice(node_version, vite_shared::MIN_SUPPORTED_NODE);
+
+    let runtime_bin = runtime.get_bin_prefix();
+    let pm = PackageManager::builder(cwd).detect_only(&runtime_bin).await.map_err(map_pm_error)?;
+
+    match command {
+        Commands::Run { args } => {
+            // vpr/vp run <script> -> <pm> run <script> [args] (nr-style).
+            // NOTE: `resolve_install_command` auto-prepends "install", so it can't
+            // be reused here. Build the args + envs directly: bin_path = pm's bin
+            // name, PATH = node runtime bin (for the pm shim) + pm's bin dir.
+            let mut full_args = vec!["run".to_string()];
+            full_args.extend(args.iter().cloned());
+            let pm_bin_prefix = pm.get_bin_prefix();
+            let envs = build_passthrough_envs(&runtime_bin, Some(&pm_bin_prefix));
+            let bin_name = pm.bin_name.to_string();
+            Ok(run_command(&bin_name, full_args, &envs, cwd).await?)
+        }
+        Commands::PackageManager(pm_command) => {
+            // Reuse the full PM dispatch with the detect-only pm. dispatch_with_pm
+            // internally calls pm.run_*_command whose envs.PATH = pm.get_bin_prefix()
+            // (detect_only set it: explicit version -> vp download dir bin; npm no
+            // config -> node runtime bin). Prepend the node runtime bin to the
+            // process PATH so JS-based PM shims (pnpm/yarn) can resolve `node`
+            // via #!/usr/bin/env node.
+            prepend_to_path_env(&runtime_bin, PrependOptions { dedupe_anywhere: true });
+            Ok(vite_pm_cli::dispatch::dispatch_with_pm(cwd, pm_command.clone(), &pm).await?)
+        }
+        other => Err(Error::UserMessage(
+            format!("Passthrough mode does not support this command: {other:?}").into(),
+        )),
+    }
+}
+
+/// Map `vite_error::Error` from `detect_only` to a user-facing message when the
+/// project has no explicit, compatible package manager version.
+#[allow(dead_code)] // called by execute
+fn map_pm_error(e: vite_error::Error) -> Error {
+    match e {
+        vite_error::Error::UnrecognizedPackageManager => Error::UserMessage(
+            "Passthrough mode could not resolve a compatible package manager version. \
+             Please specify one in package.json (e.g. \"packageManager\": \"pnpm@9.15.0\") \
+             or upgrade Node."
+                .into(),
+        ),
+        other => Error::Install(other),
+    }
+}
+
+/// Build the PATH env for passthrough: PM bin dir first (so the pm binary is
+/// found first), then the node runtime bin (for the pm shim's
+/// `#!/usr/bin/env node`), then the existing PATH.
+///
+/// Uses `env::split_paths` / `env::join_paths` for correct platform-aware
+/// separator handling and non-UTF-8 path safety.
+#[allow(dead_code)] // called by execute
+fn build_passthrough_envs(
+    runtime_bin: &AbsolutePath,
+    pm_bin_prefix: Option<&AbsolutePath>,
+) -> HashMap<String, String> {
+    use std::env;
+
+    let current = env::var_os("PATH").unwrap_or_default();
+    let mut paths: Vec<_> = env::split_paths(&current).collect();
+
+    // PM bin dir first (so the pm binary resolves before node).
+    if let Some(pm_bin) = pm_bin_prefix {
+        let pm = pm_bin.as_path().to_path_buf();
+        if !paths.iter().any(|p| *p == pm) {
+            paths.insert(0, pm);
+        }
+    }
+
+    // Node runtime bin next (for pm shim's #!/usr/bin/env node).
+    let rt = runtime_bin.as_path().to_path_buf();
+    if !paths.iter().any(|p| *p == rt) {
+        paths.insert(0, rt);
+    }
+
+    let path_string =
+        env::join_paths(paths).map(|p| p.to_string_lossy().into_owned()).unwrap_or_default();
+
+    let mut envs = HashMap::new();
+    envs.insert("PATH".to_string(), path_string);
+    envs
+}
+
+/// Resolve the project's Node version string (if any), without forcing a
+/// download. Used by the passthrough precheck to decide activation.
+///
+/// Returns `None` when the project has no Node version source (no .node-version,
+/// no devEngines.runtime, no engines.node) — in that case the original path
+/// runs (which falls back to CLI/LTS runtime, above the minimum).
+///
+/// Returns `None` on resolution errors (I/O, parse) — the caller falls through
+/// to the normal CLI path, which has its own error handling.
+pub(crate) async fn resolve_project_node_version(cwd: &vite_path::AbsolutePath) -> Option<String> {
+    use vite_js_runtime::resolve_node_version;
+    // walk_up=true to match ensure_project_runtime's resolution
+    // (has_valid_version_source uses resolve_node_version(path, true) at
+    // js_executor.rs:189); using false here could disagree with the runtime
+    // version actually downloaded, causing passthrough to mis-fire.
+    let resolution = resolve_node_version(cwd, true).await.ok()??;
+    Some(resolution.version.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use vite_path::AbsolutePathBuf;
+
+    #[test]
+    fn run_is_eligible() {
+        assert!(is_eligible(&Commands::Run { args: vec![] }));
+    }
+
+    #[test]
+    fn install_is_eligible() {
+        assert!(is_eligible(&Commands::PackageManager(
+            vite_pm_cli::PackageManagerCommand::Install {
+                prod: false,
+                dev: false,
+                no_optional: false,
+                frozen_lockfile: false,
+                no_frozen_lockfile: false,
+                lockfile_only: false,
+                prefer_offline: false,
+                offline: false,
+                force: false,
+                ignore_scripts: false,
+                no_lockfile: false,
+                fix_lockfile: false,
+                shamefully_hoist: false,
+                resolution_only: false,
+                silent: false,
+                filter: None,
+                workspace_root: false,
+                save_exact: false,
+                save_peer: false,
+                save_optional: false,
+                save_catalog: false,
+                global: false,
+                node: None,
+                concurrency: None,
+                packages: None,
+                pass_through_args: None,
+            }
+        )));
+    }
+
+    #[test]
+    fn dev_build_test_not_eligible() {
+        assert!(!is_eligible(&Commands::Dev { args: vec![] }));
+        assert!(!is_eligible(&Commands::Build { args: vec![] }));
+        assert!(!is_eligible(&Commands::Test { args: vec![] }));
+    }
+
+    #[test]
+    fn global_install_not_eligible() {
+        // Global PM operations should use VP's managed install system, not passthrough.
+        assert!(is_eligible(&Commands::PackageManager(
+            vite_pm_cli::PackageManagerCommand::Install {
+                prod: false,
+                dev: false,
+                no_optional: false,
+                frozen_lockfile: false,
+                no_frozen_lockfile: false,
+                lockfile_only: false,
+                prefer_offline: false,
+                offline: false,
+                force: false,
+                ignore_scripts: false,
+                no_lockfile: false,
+                fix_lockfile: false,
+                shamefully_hoist: false,
+                resolution_only: false,
+                silent: false,
+                filter: None,
+                workspace_root: false,
+                save_exact: false,
+                save_peer: false,
+                save_optional: false,
+                save_catalog: false,
+                global: false,
+                node: None,
+                concurrency: None,
+                packages: None,
+                pass_through_args: None,
+            }
+        )));
+        assert!(!is_eligible(&Commands::PackageManager(
+            vite_pm_cli::PackageManagerCommand::Install {
+                prod: false,
+                dev: false,
+                no_optional: false,
+                frozen_lockfile: false,
+                no_frozen_lockfile: false,
+                lockfile_only: false,
+                prefer_offline: false,
+                offline: false,
+                force: false,
+                ignore_scripts: false,
+                no_lockfile: false,
+                fix_lockfile: false,
+                shamefully_hoist: false,
+                resolution_only: false,
+                silent: false,
+                filter: None,
+                workspace_root: false,
+                save_exact: false,
+                save_peer: false,
+                save_optional: false,
+                save_catalog: false,
+                global: true,
+                node: None,
+                concurrency: None,
+                packages: Some(vec!["express".into()]),
+                pass_through_args: None,
+            }
+        )));
+    }
+
+    #[test]
+    fn should_passthrough_combines_eligible_and_low_node() {
+        assert!(should_passthrough(&Commands::Run { args: vec![] }, "14.15.0"));
+        assert!(!should_passthrough(&Commands::Run { args: vec![] }, "22.18.0"));
+        // high node but eligible command -> no passthrough
+        assert!(!should_passthrough(&Commands::Dev { args: vec![] }, "14.15.0"));
+    }
+
+    #[test]
+    fn build_envs_prepends_runtime_bin_to_path() {
+        let tmp = tempfile::tempdir().unwrap();
+        let bin = AbsolutePathBuf::new(tmp.path().join("bin")).unwrap();
+        let envs = build_passthrough_envs(&bin, None);
+        let path = envs.get("PATH").expect("PATH must be present");
+        assert!(path.starts_with(&bin.to_string()), "PATH must start with runtime bin");
+    }
+
+    #[test]
+    fn build_envs_prepends_both_runtime_and_pm_bin() {
+        let tmp = tempfile::tempdir().unwrap();
+        let runtime_bin = AbsolutePathBuf::new(tmp.path().join("node_bin")).unwrap();
+        let pm_bin = AbsolutePathBuf::new(tmp.path().join("pm_bin")).unwrap();
+        let envs = build_passthrough_envs(&runtime_bin, Some(&pm_bin));
+        let path = envs.get("PATH").expect("PATH must be present");
+        assert!(
+            path.starts_with(&pm_bin.to_string()),
+            "PATH must start with PM bin dir, got: {path}"
+        );
+        assert!(path.contains(&runtime_bin.to_string()), "PATH must contain runtime bin");
+    }
+
+    #[test]
+    fn map_pm_error_unrecognized_is_user_message() {
+        let err = map_pm_error(vite_error::Error::UnrecognizedPackageManager);
+        assert!(matches!(err, Error::UserMessage(_)));
+    }
+}
diff --git a/crates/vite_global_cli/src/commands/vpr.rs b/crates/vite_global_cli/src/commands/vpr.rs
index e043b9c8b0..9095455b4b 100644
--- a/crates/vite_global_cli/src/commands/vpr.rs
+++ b/crates/vite_global_cli/src/commands/vpr.rs
@@ -2,18 +2,64 @@
 //!
 //! Standalone shorthand for `vp run`. Delegates to the local or global
 //! vite-plus CLI to execute tasks.
+//!
+//! On low-Node projects (Node < 20.19.0), degrades to passthrough mode —
+//! runs the project's own package manager directly without loading the
+//! Vite+ JS CLI. See `commands::passthrough` for details.
 
 use vite_path::AbsolutePath;
 use vite_shared::output;
 
+use crate::cli::Commands;
+
 /// Main entry point for vpr execution.
 ///
 /// Called from shim dispatch when `argv[0]` is `vpr`.
+///
+/// On low-Node projects, the passthrough precheck fires before delegating
+/// to the JS CLI — this mirrors the precheck in `run_command_with_options`
+/// for the `vp run` path, but here we come through the `vpr` shim.
 pub async fn execute_vpr(args: &[String], cwd: &AbsolutePath) -> i32 {
     if crate::help::maybe_print_unified_delegate_help("run", args, true) {
         return 0;
     }
 
+    // Passthrough precheck: if the project's Node is below the supported
+    // minimum, bypass the Vite+ JS CLI and run the project's package manager
+    // directly. This mirrors the precheck in run_command_with_options.
+    if let Some(node_version) =
+        crate::commands::passthrough::resolve_project_node_version(cwd).await
+    {
+        if crate::commands::passthrough::should_passthrough(
+            &Commands::Run { args: args.to_vec() },
+            &node_version,
+        ) {
+            let mut executor = crate::js_executor::JsExecutor::new(None);
+            match executor.ensure_project_runtime(cwd).await {
+                Ok(runtime) => {
+                    match crate::commands::passthrough::execute(
+                        cwd,
+                        &Commands::Run { args: args.to_vec() },
+                        runtime,
+                    )
+                    .await
+                    {
+                        Ok(status) => return status.code().unwrap_or(1),
+                        Err(e) => {
+                            output::error(&e.to_string());
+                            return 1;
+                        }
+                    }
+                }
+                Err(e) => {
+                    output::error(&e.to_string());
+                    return 1;
+                }
+            }
+        }
+    }
+
+    // Original path: delegate to the local vite-plus JS CLI.
     let cwd_buf = cwd.to_absolute_path_buf();
     match super::delegate::execute(cwd_buf, "run", args).await {
         Ok(status) => status.code().unwrap_or(1),
diff --git a/crates/vite_global_cli/src/commands/vpx.rs b/crates/vite_global_cli/src/commands/vpx.rs
index bacf518a36..0dc6545b72 100644
--- a/crates/vite_global_cli/src/commands/vpx.rs
+++ b/crates/vite_global_cli/src/commands/vpx.rs
@@ -6,9 +6,13 @@
 //! 2. Global vp packages (installed via `vp install -g`)
 //! 3. System PATH (excluding vite-plus bin directory)
 //! 4. Remote download via `vp dlx`
+//!
+//! On low-Node projects (Node < 20.19.0), steps 2 and 4 are adapted:
+//! - Step 2 is skipped (global lookup requires the Vite+ JS CLI)
+//! - Step 4 uses passthrough mode (project's PM runs dlx directly)
 
 use vite_path::{AbsolutePath, AbsolutePathBuf};
-use vite_shared::{PrependOptions, output, prepend_to_path_env};
+use vite_shared::{PrependOptions, is_node_below_min, output, prepend_to_path_env};
 
 use crate::{commands::env::config, shim::dispatch};
 
@@ -85,7 +89,7 @@ pub async fn execute_vpx(args: &[String], cwd: &AbsolutePath) -> i32 {
 
     // If no version spec and no --package flag, try local → global → PATH lookup
     if !has_version_spec(cmd_spec) && flags.packages.is_empty() && !flags.shell_mode {
-        // 1. Try local node_modules/.bin
+        // 1. Try local node_modules/.bin (pure filesystem -- works on low-Node)
         if let Some(local_bin) = find_local_binary(cwd, &cmd_name) {
             tracing::debug!("vpx: found local binary at {}", local_bin.as_path().display());
             prepend_node_modules_bin_to_path(cwd);
@@ -93,13 +97,20 @@ pub async fn execute_vpx(args: &[String], cwd: &AbsolutePath) -> i32 {
             return crate::shim::exec::exec_tool(&local_bin, &cmd_args);
         }
 
-        // 2. Try global vp packages
-        if let Some(global_bin) = find_global_binary(&cmd_name).await {
-            tracing::debug!("vpx: found global binary at {}", global_bin.path.as_path().display());
-            return execute_global_binary(global_bin, &positional[1..], cwd).await;
+        // 2. Try global vp packages (requires JS CLI -- skip on low-Node).
+        //    Deferred is_low_node check: only resolves node version when we
+        //    actually need the global binary lookup or dlx fallback.
+        if !is_low_node(cwd).await {
+            if let Some(global_bin) = find_global_binary(&cmd_name).await {
+                tracing::debug!(
+                    "vpx: found global binary at {}",
+                    global_bin.path.as_path().display()
+                );
+                return execute_global_binary(global_bin, &positional[1..], cwd).await;
+            }
         }
 
-        // 3. Try system PATH (excluding vite-plus bin dir)
+        // 3. Try system PATH (excluding vite-plus bin dir -- works on low-Node)
         if let Some(path_bin) = find_on_path(&cmd_name) {
             tracing::debug!("vpx: found on PATH at {}", path_bin.as_path().display());
             prepend_node_modules_bin_to_path(cwd);
@@ -109,6 +120,12 @@ pub async fn execute_vpx(args: &[String], cwd: &AbsolutePath) -> i32 {
     }
 
     // 4. Fall back to dlx (remote download)
+    if is_low_node(cwd).await {
+        // Low-Node passthrough: use the project's package manager directly.
+        // This bypasses the Vite+ JS CLI which cannot load on old Node.
+        return execute_dlx_passthrough(cwd, &flags, &positional).await;
+    }
+
     if let Err(e) = super::prepend_js_runtime_to_path_env(cwd).await {
         output::error(&format!("vpx: {e}"));
         return 1;
@@ -128,6 +145,81 @@ pub async fn execute_vpx(args: &[String], cwd: &AbsolutePath) -> i32 {
     }
 }
 
+/// Check if the project's resolved Node version is below the Vite+ minimum.
+///
+/// Returns `true` when passthrough mode should activate. Delegates to the
+/// shared resolve function from `commands::passthrough`.
+async fn is_low_node(cwd: &AbsolutePath) -> bool {
+    match crate::commands::passthrough::resolve_project_node_version(cwd).await {
+        Some(version) => is_node_below_min(&version),
+        None => false,
+    }
+}
+
+/// Execute dlx in passthrough mode: detect the project's PM (no devEngines
+/// pin) and run `<pm> dlx <args>` directly, bypassing the Vite+ JS CLI.
+async fn execute_dlx_passthrough(
+    cwd: &AbsolutePath,
+    flags: &VpxFlags,
+    positional: &[String],
+) -> i32 {
+    use vite_install::PackageManager;
+
+    use crate::js_executor::JsExecutor;
+
+    // Resolve the Node runtime (download if needed) to get the bin dir.
+    let mut executor = JsExecutor::new(None);
+    let runtime = match executor.ensure_project_runtime(cwd).await {
+        Ok(r) => r,
+        Err(e) => {
+            output::error(&format!("vpx: {e}"));
+            return 1;
+        }
+    };
+    let runtime_bin = runtime.get_bin_prefix();
+
+    // Detect the package manager without writing devEngines.
+    let pm = match PackageManager::builder(cwd)
+        .detect_only(&runtime_bin)
+        .await
+    {
+        Ok(pm) => pm,
+        Err(e) => {
+            output::error(&format!(
+                "vpx: Could not resolve a package manager for passthrough: {e}\n\
+                 Please specify one in package.json (e.g. \"packageManager\": \"pnpm@9.15.0\") \
+                 or upgrade Node."
+            ));
+            return 1;
+        }
+    };
+
+    // Print the passthrough notice.
+    let node_version = runtime.version();
+    crate::commands::passthrough::print_passthrough_notice(
+        node_version,
+        vite_shared::MIN_SUPPORTED_NODE,
+    );
+
+    // Prepend Node runtime bin to process PATH so PM shims can find `node`.
+    prepend_to_path_env(&runtime_bin, PrependOptions { dedupe_anywhere: true });
+
+    // Dispatch dlx via the project's PM.
+    let dlx = vite_pm_cli::PackageManagerCommand::Dlx {
+        package: flags.packages.clone(),
+        shell_mode: flags.shell_mode,
+        silent: flags.silent,
+        args: positional.to_vec(),
+    };
+    match vite_pm_cli::dispatch::dispatch_with_pm(cwd, dlx, &pm).await {
+        Ok(status) => status.code().unwrap_or(1),
+        Err(e) => {
+            output::error(&format!("vpx: {e}"));
+            1
+        }
+    }
+}
+
 /// Find a binary in globally installed vp packages.
 ///
 /// Uses the dispatch helpers to look up BinConfig and PackageMetadata.
diff --git a/crates/vite_global_cli/tests/passthrough_e2e.rs b/crates/vite_global_cli/tests/passthrough_e2e.rs
new file mode 100644
index 0000000000..2c2ad32741
--- /dev/null
+++ b/crates/vite_global_cli/tests/passthrough_e2e.rs
@@ -0,0 +1,65 @@
+//! End-to-end: low-Node project degrades `vpr`/`vp i` to passthrough.
+//!
+//! Requires VP_PASSTHROUGH_E2E=1 and a pre-cached Node 14 + pnpm runtime,
+//! because it exercises real downloads. Skipped otherwise.
+
+use std::process::Command;
+
+fn e2e_enabled() -> bool {
+    std::env::var("VP_PASSTHROUGH_E2E").is_ok()
+}
+
+#[test]
+fn vpr_passthrough_runs_project_script_on_low_node() {
+    if !e2e_enabled() {
+        eprintln!("skipping (set VP_PASSTHROUGH_E2E=1)");
+        return;
+    }
+    // Fixture: project with .node-version=14.15.0, packageManager=pnpm@<cached>,
+    // and a `dev` script that echoes a marker. Assert marker appears in stdout
+    // and package.json is NOT mutated with devEngines.
+    let project = setup_low_node_project("pnpm");
+    let output = Command::new(env!("CARGO_BIN_EXE_vp"))
+        .args(["run", "dev"])
+        .current_dir(&project)
+        .output()
+        .expect("vp binary");
+    assert!(output.status.success(), "vpr dev should passthrough");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("PASSTHROUGH_MARKER"), "script must run");
+    let pkg = std::fs::read_to_string(project.join("package.json")).unwrap();
+    assert!(!pkg.contains("devEngines"), "must not write devEngines");
+}
+
+#[test]
+fn vp_install_passthrough_on_low_node() {
+    if !e2e_enabled() {
+        eprintln!("skipping (set VP_PASSTHROUGH_E2E=1)");
+        return;
+    }
+    let project = setup_low_node_project("pnpm");
+    let output = Command::new(env!("CARGO_BIN_EXE_vp"))
+        .args(["i"])
+        .current_dir(&project)
+        .output()
+        .expect("vp binary");
+    assert!(output.status.success(), "vp i should passthrough");
+    let pkg = std::fs::read_to_string(project.join("package.json")).unwrap();
+    assert!(!pkg.contains("devEngines"), "must not write devEngines");
+}
+
+fn setup_low_node_project(pm: &str) -> std::path::PathBuf {
+    let dir = tempfile::tempdir().unwrap().keep();
+    std::fs::write(dir.join(".node-version"), "14.15.0\n").unwrap();
+    // packageManager pinned to a Node-14-compatible version (caller ensures cached).
+    let version = match pm {
+        "pnpm" => "7.33.0",
+        "yarn" => "1.22.0",
+        _ => "6.14.8",
+    };
+    let pkg_json = format!(
+        r#"{{"name":"e2e","scripts":{{"dev":"echo PASSTHROUGH_MARKER"}},"packageManager":"{pm}@{version}"}}"#
+    );
+    std::fs::write(dir.join("package.json"), pkg_json).unwrap();
+    dir
+}
diff --git a/crates/vite_install/src/package_manager.rs b/crates/vite_install/src/package_manager.rs
index 5d8aa1c1ff..09ef1a121c 100644
--- a/crates/vite_install/src/package_manager.rs
+++ b/crates/vite_install/src/package_manager.rs
@@ -229,6 +229,82 @@ impl PackageManagerBuilder {
         };
         Ok(package_manager)
     }
+
+    /// Build a `PackageManager` for passthrough mode: detect and download the
+    /// explicitly-configured package manager version WITHOUT writing
+    /// `devEngines.packageManager` to package.json.
+    ///
+    /// Resolution rules (mirrors `build()` detection, diverges on pin + fallback):
+    /// - Explicit version (`packageManager` / `devEngines.packageManager` with a
+    ///   version) → download that version (feature preserved), skip pin.
+    /// - npm with no explicit version → use the Node-bundled npm at
+    ///   `node_bin_prefix` (compatible with the active Node).
+    /// - pnpm/yarn/bun with no explicit version → `Error::UnrecognizedPackageManager`
+    ///   (caller surfaces a "specify a version" message); we never download an
+    ///   unverified `latest` that may be incompatible with the active Node.
+    ///
+    /// `node_bin_prefix` is the bin directory of the resolved project Node
+    /// runtime (where the bundled `npm` lives).
+    pub async fn detect_only(
+        &self,
+        node_bin_prefix: &AbsolutePath,
+    ) -> Result<PackageManager, Error> {
+        let (workspace_root, _cwd) = find_workspace_root(&self.cwd)?;
+        let (package_manager_type, version_or_req, hash, source) =
+            get_package_manager_type_and_version(&workspace_root, self.client_override)?;
+
+        let has_explicit_version = matches!(
+            source,
+            PackageManagerSource::PackageManagerField
+                | PackageManagerSource::DevEnginesPackageManager
+        ) && version_or_req.as_str() != "*"
+            && !version_or_req.is_empty();
+
+        // Non-npm without an explicit version: refuse to guess/download latest.
+        if !has_explicit_version && package_manager_type != PackageManagerType::Npm {
+            return Err(Error::UnrecognizedPackageManager);
+        }
+
+        let (install_dir, package_name, version, bin_name) = if has_explicit_version {
+            let (install_dir, package_name, version) =
+                download_package_manager(package_manager_type, &version_or_req, hash.as_deref())
+                    .await?;
+            (install_dir, package_name, version, package_manager_type.to_string().into())
+        } else {
+            // npm, no explicit version: use Node-bundled npm.
+            // Set install_dir to the *parent* of node_bin_prefix (the Node
+            // installation root) so that get_bin_prefix() — which does
+            // install_dir.join("bin") — produces the correct bin directory
+            // (e.g. <node_root>/bin/) rather than a doubled bin/bin/ path.
+            let node_bin_buf = node_bin_prefix.to_absolute_path_buf();
+            let install_dir = node_bin_buf
+                .parent()
+                .map(|p| p.to_absolute_path_buf())
+                .unwrap_or(node_bin_buf);
+            (
+                install_dir,
+                "npm".into(),
+                "bundled".into(),
+                "npm".into(),
+            )
+        };
+
+        let is_monorepo = matches!(
+            workspace_root.workspace_file,
+            WorkspaceFile::PnpmWorkspaceYaml(_) | WorkspaceFile::NpmWorkspaceJson(_)
+        );
+
+        Ok(PackageManager {
+            client: package_manager_type,
+            package_name,
+            version,
+            hash,
+            bin_name,
+            workspace_root: workspace_root.path.to_absolute_path_buf(),
+            is_monorepo,
+            install_dir,
+        })
+    }
 }
 
 impl PackageManager {
@@ -3475,4 +3551,68 @@ mod tests {
         // Release lock
         lock_file1.unlock().expect("Failed to unlock file 1");
     }
+
+    #[tokio::test]
+    async fn detect_only_npm_no_config_uses_node_bundled_npm() {
+        // Project with package-lock.json (npm) but no explicit version.
+        let tmp = tempfile::tempdir().unwrap();
+        let project = AbsolutePathBuf::new(tmp.path().to_path_buf()).unwrap();
+        tokio::fs::write(project.join("package.json"), r#"{"name":"x"}"#).await.unwrap();
+        tokio::fs::write(project.join("package-lock.json"), "{}").await.unwrap();
+        // Mimic real Node layout: <root>/node/bin/ contains the node binary.
+        // The node_bin_prefix is the "bin" directory inside the Node install.
+        let node_root = tmp.path().join("node");
+        let node_bin = node_root.join("bin");
+        tokio::fs::create_dir_all(&node_bin).await.unwrap();
+        let node_bin = AbsolutePathBuf::new(node_bin).unwrap();
+
+        let pm = PackageManager::builder(&project).detect_only(&node_bin).await.unwrap();
+        assert_eq!(pm.client, PackageManagerType::Npm);
+        // install_dir points to the parent of node_bin (Node installation root),
+        // so get_bin_prefix() == node_bin (install_dir.join("bin")).
+        let expected_install_dir = AbsolutePathBuf::new(node_root).unwrap();
+        assert_eq!(pm.install_dir, expected_install_dir);
+        assert_eq!(pm.get_bin_prefix(), node_bin);
+        // bin_name resolves to "npm"
+        assert_eq!(pm.bin_name.as_str(), "npm");
+    }
+
+    #[tokio::test]
+    async fn detect_only_pnpm_no_config_errors() {
+        // Project with pnpm-lock.yaml but no explicit version -> error (not download latest).
+        let tmp = tempfile::tempdir().unwrap();
+        let project = AbsolutePathBuf::new(tmp.path().to_path_buf()).unwrap();
+        tokio::fs::write(project.join("package.json"), r#"{"name":"x"}"#).await.unwrap();
+        tokio::fs::write(project.join("pnpm-lock.yaml"), "").await.unwrap();
+        let node_bin = AbsolutePathBuf::new(tmp.path().join("node_bin")).unwrap();
+        tokio::fs::create_dir_all(&node_bin).await.unwrap();
+
+        let result = PackageManager::builder(&project).detect_only(&node_bin).await;
+        assert!(matches!(result, Err(Error::UnrecognizedPackageManager)));
+    }
+
+    #[tokio::test]
+    async fn detect_only_never_writes_dev_engines() {
+        // Even with an explicit version (which triggers download), devEngines must NOT be written.
+        let tmp = tempfile::tempdir().unwrap();
+        let project = AbsolutePathBuf::new(tmp.path().to_path_buf()).unwrap();
+        tokio::fs::write(
+            project.join("package.json"),
+            r#"{"name":"x","packageManager":"npm@10.0.0"}"#,
+        )
+        .await
+        .unwrap();
+        let node_bin = AbsolutePathBuf::new(tmp.path().join("node_bin")).unwrap();
+        tokio::fs::create_dir_all(&node_bin).await.unwrap();
+
+        // detect_only may attempt to download npm@10.0.0; in tests we only assert
+        // the package.json is NOT mutated with devEngines. If download is unreachable
+        // in CI, gate the devEngines assertion behind the download succeeding.
+        let before = tokio::fs::read_to_string(project.join("package.json")).await.unwrap();
+        let _ = PackageManager::builder(&project).detect_only(&node_bin).await;
+        let after = tokio::fs::read_to_string(project.join("package.json")).await.unwrap();
+        assert!(!after.contains("devEngines"));
+        // Ensure we didn't accidentally rewrite other content
+        assert_eq!(before, after);
+    }
 }
diff --git a/crates/vite_pm_cli/Cargo.toml b/crates/vite_pm_cli/Cargo.toml
index b443b4bf54..b59d822181 100644
--- a/crates/vite_pm_cli/Cargo.toml
+++ b/crates/vite_pm_cli/Cargo.toml
@@ -23,5 +23,8 @@ vite_workspace = { workspace = true }
 [lib]
 doctest = false
 
+[dev-dependencies]
+tempfile = { workspace = true }
+
 [lints]
 workspace = true
diff --git a/crates/vite_pm_cli/src/dispatch.rs b/crates/vite_pm_cli/src/dispatch.rs
index 6826cd0141..aa1bc12147 100644
--- a/crates/vite_pm_cli/src/dispatch.rs
+++ b/crates/vite_pm_cli/src/dispatch.rs
@@ -11,6 +11,7 @@ use vite_install::commands::{
     unlink::UnlinkCommandOptions, update::UpdateCommandOptions, view::ViewCommandOptions,
     why::WhyCommandOptions,
 };
+use vite_install::PackageManager;
 use vite_path::AbsolutePath;
 
 use crate::{cli::PackageManagerCommand, error::Error, handlers};
@@ -18,6 +19,28 @@ use crate::{cli::PackageManagerCommand, error::Error, handlers};
 pub async fn dispatch(
     cwd: &AbsolutePath,
     command: PackageManagerCommand,
+) -> Result<ExitStatus, Error> {
+    // Dlx is special-cased: `run_dlx` has a `PackageJsonNotFound → npx` fallback
+    // that must be preserved. The `build_for_dispatch` path would propagate
+    // `PackageJsonNotFound` via `?`, making the fallback dead code. Call `run_dlx`
+    // directly to preserve the original behavior.
+    if let PackageManagerCommand::Dlx { package, shell_mode, silent, args } = command {
+        return handlers::run_dlx(cwd, package, shell_mode, silent, args).await;
+    }
+    let pm = handlers::build_for_dispatch(cwd, &command).await?;
+    dispatch_with_pm(cwd, command, &pm).await
+}
+
+/// Dispatch using an externally-provided [`PackageManager`] (no internal build/pin).
+///
+/// Used by passthrough mode, where the pm comes from
+/// `PackageManager::detect_only`. The match body is identical to the original
+/// `dispatch` (zero behavior drift) — only the handler calls take the injected
+/// `pm` via the `*_with_pm` variants.
+pub async fn dispatch_with_pm(
+    cwd: &AbsolutePath,
+    command: PackageManagerCommand,
+    pm: &PackageManager,
 ) -> Result<ExitStatus, Error> {
     match command {
         PackageManagerCommand::Install {
@@ -70,7 +93,7 @@ pub async fn dispatch(
                     allow_build: None,
                     pass_through_args: pass_through_args.as_deref(),
                 };
-                return handlers::run_add(cwd, &options).await;
+                return handlers::run_add_with_pm(cwd, &options, pm).await;
             }
 
             let options = InstallCommandOptions {
@@ -93,7 +116,7 @@ pub async fn dispatch(
                 workspace_root,
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_install(cwd, &options).await
+            handlers::run_install_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Add {
@@ -132,7 +155,7 @@ pub async fn dispatch(
                 allow_build: allow_build.as_deref(),
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_add(cwd, &options).await
+            handlers::run_add_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Remove {
@@ -162,7 +185,7 @@ pub async fn dispatch(
                 save_prod,
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_remove(cwd, &options).await
+            handlers::run_remove_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Update {
@@ -197,13 +220,13 @@ pub async fn dispatch(
                 workspace_only: workspace,
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_update(cwd, &options).await
+            handlers::run_update_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Dedupe { check, pass_through_args } => {
             let options =
                 DedupeCommandOptions { check, pass_through_args: pass_through_args.as_deref() };
-            handlers::run_dedupe(cwd, &options).await
+            handlers::run_dedupe_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Outdated {
@@ -237,7 +260,7 @@ pub async fn dispatch(
                 global,
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_outdated(cwd, &options).await
+            handlers::run_outdated_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Why {
@@ -272,7 +295,7 @@ pub async fn dispatch(
                 find_by: find_by.as_deref(),
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_why(cwd, &options).await
+            handlers::run_why_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Info { package, field, json, pass_through_args } => {
@@ -282,7 +305,7 @@ pub async fn dispatch(
                 json,
                 pass_through_args: pass_through_args.as_deref(),
             };
-            handlers::run_info(cwd, &options).await
+            handlers::run_info_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Link { package, args } => {
@@ -290,7 +313,7 @@ pub async fn dispatch(
                 package: package.as_deref(),
                 pass_through_args: pass_through_slice(&args),
             };
-            handlers::run_link(cwd, &options).await
+            handlers::run_link_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Unlink { package, recursive, args } => {
@@ -299,14 +322,16 @@ pub async fn dispatch(
                 recursive,
                 pass_through_args: pass_through_slice(&args),
             };
-            handlers::run_unlink(cwd, &options).await
+            handlers::run_unlink_with_pm(cwd, &options, pm).await
         }
 
         PackageManagerCommand::Dlx { package, shell_mode, silent, args } => {
-            handlers::run_dlx(cwd, package, shell_mode, silent, args).await
+            handlers::run_dlx_with_pm(cwd, package, shell_mode, silent, args, pm).await
         }
 
-        PackageManagerCommand::Pm(pm_command) => handlers::run_pm_subcommand(cwd, pm_command).await,
+        PackageManagerCommand::Pm(pm_command) => {
+            handlers::run_pm_subcommand_with_pm(cwd, pm_command, pm).await
+        }
     }
 }
 
diff --git a/crates/vite_pm_cli/src/handlers.rs b/crates/vite_pm_cli/src/handlers.rs
index 1670c5ec4d..aa48c381f9 100644
--- a/crates/vite_pm_cli/src/handlers.rs
+++ b/crates/vite_pm_cli/src/handlers.rs
@@ -44,7 +44,8 @@ use vite_path::AbsolutePath;
 
 use crate::{
     cli::{
-        ConfigCommands, DistTagCommands, OwnerCommands, PmCommands, StageCommands, TokenCommands,
+        ConfigCommands, DistTagCommands, OwnerCommands, PackageManagerCommand, PmCommands,
+        StageCommands, TokenCommands,
     },
     error::Error,
     helpers::{build_package_manager, build_package_manager_or_npm_default, ensure_package_json},
@@ -56,6 +57,16 @@ pub async fn run_add(
 ) -> Result<ExitStatus, Error> {
     ensure_package_json(cwd).await?;
     let pm = PackageManager::builder(cwd).build_with_default().await?;
+    run_add_with_pm(cwd, options, &pm).await
+}
+
+/// Run `add` with an externally-provided `PackageManager` (no internal build/pin).
+/// Used by passthrough mode, where the pm comes from `detect_only`.
+pub async fn run_add_with_pm(
+    cwd: &AbsolutePath,
+    options: &AddCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_add_command(options, cwd).await?)
 }
 
@@ -65,6 +76,15 @@ pub async fn run_install(
 ) -> Result<ExitStatus, Error> {
     ensure_package_json(cwd).await?;
     let pm = PackageManager::builder(cwd).build_with_default().await?;
+    run_install_with_pm(cwd, options, &pm).await
+}
+
+/// Run `install` with an externally-provided `PackageManager` (no internal build/pin).
+pub async fn run_install_with_pm(
+    cwd: &AbsolutePath,
+    options: &InstallCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_install_command(options, cwd).await?)
 }
 
@@ -73,6 +93,14 @@ pub async fn run_remove(
     options: &RemoveCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_remove_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_remove_with_pm(
+    cwd: &AbsolutePath,
+    options: &RemoveCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_remove_command(options, cwd).await?)
 }
 
@@ -81,6 +109,14 @@ pub async fn run_update(
     options: &UpdateCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_update_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_update_with_pm(
+    cwd: &AbsolutePath,
+    options: &UpdateCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_update_command(options, cwd).await?)
 }
 
@@ -89,6 +125,14 @@ pub async fn run_dedupe(
     options: &DedupeCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_dedupe_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_dedupe_with_pm(
+    cwd: &AbsolutePath,
+    options: &DedupeCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_dedupe_command(options, cwd).await?)
 }
 
@@ -97,6 +141,14 @@ pub async fn run_outdated(
     options: &OutdatedCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_outdated_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_outdated_with_pm(
+    cwd: &AbsolutePath,
+    options: &OutdatedCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_outdated_command(options, cwd).await?)
 }
 
@@ -105,6 +157,14 @@ pub async fn run_why(
     options: &WhyCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_why_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_why_with_pm(
+    cwd: &AbsolutePath,
+    options: &WhyCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_why_command(options, cwd).await?)
 }
 
@@ -113,6 +173,14 @@ pub async fn run_info(
     options: &ViewCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager_or_npm_default(cwd).await?;
+    run_info_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_info_with_pm(
+    cwd: &AbsolutePath,
+    options: &ViewCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_view_command(options, cwd).await?)
 }
 
@@ -121,6 +189,14 @@ pub async fn run_link(
     options: &LinkCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_link_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_link_with_pm(
+    cwd: &AbsolutePath,
+    options: &LinkCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_link_command(options, cwd).await?)
 }
 
@@ -129,6 +205,14 @@ pub async fn run_unlink(
     options: &UnlinkCommandOptions<'_>,
 ) -> Result<ExitStatus, Error> {
     let pm = build_package_manager(cwd).await?;
+    run_unlink_with_pm(cwd, options, &pm).await
+}
+
+pub async fn run_unlink_with_pm(
+    cwd: &AbsolutePath,
+    options: &UnlinkCommandOptions<'_>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     Ok(pm.run_unlink_command(options, cwd).await?)
 }
 
@@ -165,6 +249,37 @@ pub async fn run_dlx(
     }
 }
 
+/// Run `dlx` with an externally-provided `PackageManager` (no internal build/pin).
+///
+/// Unlike `run_dlx`, this has no `PackageJsonNotFound → npx` fallback — passthrough
+/// guarantees the pm is already resolved. Takes the same scattered args as
+/// `run_dlx` and constructs the options internally (DRY with the original).
+pub async fn run_dlx_with_pm(
+    cwd: &AbsolutePath,
+    packages: Vec<String>,
+    shell_mode: bool,
+    silent: bool,
+    args: Vec<String>,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
+    if args.is_empty() {
+        return Err(Error::Other("dlx requires a package name".into()));
+    }
+
+    let package_spec = &args[0];
+    let command_args: Vec<String> = args[1..].to_vec();
+
+    let options = DlxCommandOptions {
+        packages: &packages,
+        package_spec,
+        args: &command_args,
+        shell_mode,
+        silent,
+    };
+
+    Ok(pm.run_dlx_command(&options, cwd).await?)
+}
+
 pub async fn run_pm_subcommand(
     cwd: &AbsolutePath,
     command: PmCommands,
@@ -188,6 +303,16 @@ pub async fn run_pm_subcommand(
         build_package_manager_or_npm_default(cwd).await?
     };
 
+    run_pm_subcommand_with_pm(cwd, command, &pm).await
+}
+
+/// Run a `vp pm <sub>` command with an externally-provided `PackageManager`
+/// (no internal build/pin). Used by passthrough mode.
+pub async fn run_pm_subcommand_with_pm(
+    cwd: &AbsolutePath,
+    command: PmCommands,
+    pm: &PackageManager,
+) -> Result<ExitStatus, Error> {
     match command {
         PmCommands::ApproveBuilds { packages, all, pass_through_args } => {
             let options = ApproveBuildsCommandOptions {
@@ -547,6 +672,108 @@ pub async fn run_pm_subcommand(
     }
 }
 
+/// Build the `PackageManager` for a `dispatch` call, picking the build strategy
+/// each `run_*` historically used. This preserves the original `dispatch` path's
+/// behavior (including `ensure_package_json` for install/add) so that
+/// `dispatch` → `build_for_dispatch` + `dispatch_with_pm` is a behavior-preserving
+/// refactor. `dispatch_with_pm` (passthrough) bypasses this entirely.
+pub async fn build_for_dispatch(
+    cwd: &AbsolutePath,
+    command: &PackageManagerCommand,
+) -> Result<PackageManager, Error> {
+    match command {
+        // install/add use build_with_default (+ ensure_package_json, matching run_install/run_add)
+        PackageManagerCommand::Install { .. } | PackageManagerCommand::Add { .. } => {
+            ensure_package_json(cwd).await?;
+            Ok(PackageManager::builder(cwd).build_with_default().await?)
+        }
+        // NOTE: Dlx is intentionally NOT handled here — `dispatch()` intercepts
+        // Dlx before calling `build_for_dispatch`, routing it to `run_dlx` which
+        // has the `PackageJsonNotFound → npx` fallback. If Dlx ever reaches this
+        // function, it falls through to the `_ =>` arm (build_package_manager),
+        // which will surface a clear error rather than silently losing the fallback.
+        // info uses build_package_manager_or_npm_default
+        PackageManagerCommand::Info { .. } => Ok(build_package_manager_or_npm_default(cwd).await?),
+        // pm subcommands: pick by needs_project (mirrors run_pm_subcommand)
+        PackageManagerCommand::Pm(pm_command) => {
+            let needs_project = matches!(
+                pm_command,
+                PmCommands::ApproveBuilds { .. }
+                    | PmCommands::Prune { .. }
+                    | PmCommands::Pack { .. }
+                    | PmCommands::List { .. }
+                    | PmCommands::Publish { .. }
+                    | PmCommands::Stage(StageCommands::Publish { .. })
+                    | PmCommands::Rebuild { .. }
+                    | PmCommands::Fund { .. }
+                    | PmCommands::Audit { .. }
+            );
+            if needs_project {
+                Ok(build_package_manager(cwd).await?)
+            } else {
+                Ok(build_package_manager_or_npm_default(cwd).await?)
+            }
+        }
+        // remove/update/dedupe/outdated/why/link/unlink use build_package_manager
+        _ => Ok(build_package_manager(cwd).await?),
+    }
+}
+
 fn config_location(global: bool, location: Option<&str>) -> Option<&str> {
     if global { Some("global") } else { location }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use vite_install::PackageManagerType;
+    use vite_path::AbsolutePathBuf;
+
+    #[tokio::test]
+    async fn run_install_with_pm_uses_provided_pm_without_build() {
+        // run_install_with_pm must NOT call build_package_manager — it uses the
+        // provided pm directly. With a bare package.json (no packageManager field,
+        // no lockfile), build_package_manager would return UnrecognizedPackageManager
+        // and panic the test; reaching run_install_command (which then fails on the
+        // missing npm binary, not on build) proves the build was skipped.
+        let tmp = tempfile::tempdir().unwrap();
+        let cwd = AbsolutePathBuf::new(tmp.path().to_path_buf()).unwrap();
+        tokio::fs::write(cwd.join("package.json"), r#"{"name":"x"}"#)
+            .await
+            .unwrap();
+        let pm = PackageManager {
+            client: PackageManagerType::Npm,
+            package_name: "npm".into(),
+            version: "bundled".into(),
+            hash: None,
+            bin_name: "npm".into(),
+            workspace_root: cwd.clone(),
+            is_monorepo: false,
+            install_dir: cwd.clone(),
+        };
+        let options = InstallCommandOptions {
+            prod: false,
+            dev: false,
+            no_optional: false,
+            frozen_lockfile: false,
+            no_frozen_lockfile: false,
+            lockfile_only: false,
+            prefer_offline: false,
+            offline: false,
+            force: false,
+            ignore_scripts: false,
+            no_lockfile: false,
+            fix_lockfile: false,
+            shamefully_hoist: false,
+            resolution_only: false,
+            silent: false,
+            filters: None,
+            workspace_root: false,
+            pass_through_args: None,
+        };
+        // Should not panic on build; the underlying run_command may fail (no real
+        // npm binary) but that failure is downstream of the injected pm, proving
+        // build was skipped.
+        let _ = run_install_with_pm(&cwd, &options, &pm).await;
+    }
+}
diff --git a/crates/vite_shared/Cargo.toml b/crates/vite_shared/Cargo.toml
index b117cb3487..4f4e484615 100644
--- a/crates/vite_shared/Cargo.toml
+++ b/crates/vite_shared/Cargo.toml
@@ -10,6 +10,7 @@ rust-version.workspace = true
 [dependencies]
 directories = { workspace = true }
 nix = { workspace = true, features = ["poll", "term"] }
+node-semver = { workspace = true }
 owo-colors = { workspace = true }
 serde = { workspace = true }
 # use `preserve_order` feature to preserve the order of the fields in `package.json`
diff --git a/crates/vite_shared/src/lib.rs b/crates/vite_shared/src/lib.rs
index 7ef476143f..7ad4ca991a 100644
--- a/crates/vite_shared/src/lib.rs
+++ b/crates/vite_shared/src/lib.rs
@@ -16,6 +16,7 @@ mod http;
 mod json_edit;
 pub mod output;
 mod package_json;
+pub mod passthrough;
 mod path_env;
 pub mod string_similarity;
 mod tls;
@@ -26,6 +27,7 @@ pub use error::format_error_chain;
 pub use home::get_vp_home;
 pub use http::shared_http_client;
 pub use json_edit::{JsonStyle, edit_json_object, insert_after};
+pub use passthrough::{MIN_SUPPORTED_NODE, SUPPORTED_NODE_RANGE, is_node_below_min};
 pub use package_json::{
     DevEngineDependency, DevEngineField, DevEngines, Engines, OnFail, PackageJson, dev_engine_entry,
 };
diff --git a/crates/vite_shared/src/passthrough.rs b/crates/vite_shared/src/passthrough.rs
new file mode 100644
index 0000000000..8f405b6b00
--- /dev/null
+++ b/crates/vite_shared/src/passthrough.rs
@@ -0,0 +1,120 @@
+//! Low-Node passthrough threshold and version comparison.
+//!
+//! The threshold mirrors `packages/cli/package.json#engines.node`
+//! (`"^20.19.0 || ^22.18.0 || >=24.11.0"`). Bump both together.
+
+/// Minimum supported Node.js version for the full Vite+ CLI.
+/// Below this, eligible commands degrade to passthrough mode.
+/// KEEP IN SYNC with packages/cli/package.json#engines.node.
+pub const MIN_SUPPORTED_NODE: &str = "20.19.0";
+
+/// The full engines.node constraint. Used to detect unsupported ranges like
+/// Node 21.x, 22.0–22.17, 23.x, 24.0–24.10 that pass the simple floor check
+/// but are not actually supported.
+/// KEEP IN SYNC with packages/cli/package.json#engines.node.
+pub const SUPPORTED_NODE_RANGE: &str = "^20.19.0 || ^22.18.0 || >=24.11.0";
+
+/// Returns true when passthrough should activate for the given version string.
+///
+/// Handles two cases:
+/// 1. **Exact version** (e.g. "14.15.0", "v22.18.0"): triggers if below
+///    `MIN_SUPPORTED_NODE`.
+/// 2. **Range string** from `engines.node` (e.g. ">=14",
+///    "^20.19.0 || ^22.18.0 || >=24.11.0"): triggers if the range does NOT
+///    satisfy `SUPPORTED_NODE_RANGE`, meaning the project targets an
+///    unsupported Node version.
+///
+/// Invalid inputs return false (do not trigger passthrough).
+#[must_use]
+pub fn is_node_below_min(version: &str) -> bool {
+    let trimmed = version.trim_start_matches('v');
+
+    // Case 1: exact version — simple floor check.
+    if let Ok(actual) = node_semver::Version::parse(trimmed) {
+        let Ok(min) = node_semver::Version::parse(MIN_SUPPORTED_NODE) else {
+            return false;
+        };
+        return actual < min;
+    }
+
+    // Case 2: range string from engines.node — check if ANY representative
+    // supported version satisfies the project's range. If none do, the project
+    // targets an unsupported Node version and passthrough should trigger.
+    //
+    // We test three boundary versions that cover all supported ranges:
+    //   ^20.19.0 → 20.19.0,  ^22.18.0 → 22.18.0,  >=24.11.0 → 24.11.0
+    if let Ok(range) = node_semver::Range::parse(trimmed) {
+        let any_supported = [MIN_SUPPORTED_NODE, "22.18.0", "24.11.0"]
+            .iter()
+            .filter_map(|v| node_semver::Version::parse(v).ok())
+            .any(|v| range.satisfies(&v));
+        return !any_supported;
+    }
+
+    // Unparseable: do not trigger.
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn below_min_triggers() {
+        assert!(is_node_below_min("14.15.0"));
+        assert!(is_node_below_min("18.20.0"));
+        assert!(is_node_below_min("20.18.0"));
+    }
+
+    #[test]
+    fn at_or_above_min_does_not_trigger() {
+        // boundary: exactly min is NOT below
+        assert!(!is_node_below_min("20.19.0"));
+        assert!(!is_node_below_min("20.19.1"));
+        assert!(!is_node_below_min("22.18.0"));
+        assert!(!is_node_below_min("24.11.0"));
+    }
+
+    #[test]
+    fn v_prefix_tolerated() {
+        assert!(is_node_below_min("v14.15.0"));
+    }
+
+    #[test]
+    fn invalid_version_does_not_trigger() {
+        assert!(!is_node_below_min("not-a-version"));
+        assert!(!is_node_below_min(""));
+    }
+
+    #[test]
+    fn range_below_min_triggers() {
+        // engines.node targets old Node only — 20.19.0 does NOT satisfy these ranges
+        assert!(is_node_below_min("^18.0.0"));
+        assert!(is_node_below_min("^14.0.0 || ^16.0.0 || ^18.0.0"));
+        assert!(is_node_below_min(">=14.0.0 <20.0.0"));
+    }
+
+    #[test]
+    fn range_matching_supported_does_not_trigger() {
+        // engines.node matches the Vite+ supported range
+        assert!(!is_node_below_min("^20.19.0 || ^22.18.0 || >=24.11.0"));
+        assert!(!is_node_below_min(">=20.19.0"));
+        // >=14 includes 20.19.0, so the project *could* run on a supported version
+        assert!(!is_node_below_min(">=14"));
+        assert!(!is_node_below_min(">=14.0.0"));
+    }
+
+    #[test]
+    fn range_partially_overlapping_triggers() {
+        // Node 21.x is in the range but NOT in supported set
+        assert!(is_node_below_min("^21.0.0"));
+    }
+
+    #[test]
+    fn range_partially_overlapping_with_supported_does_not_trigger() {
+        // ^22.0.0 includes 22.18.0 which IS supported → no passthrough
+        assert!(!is_node_below_min("^22.0.0"));
+        // Mixed range: ^18 excludes 20.x, but ^22 includes 22.18.0 → no passthrough
+        assert!(!is_node_below_min("^18.0.0 || ^22.0.0"));
+    }
+}
diff --git a/packages/cli/snap-tests-global/passthrough-notice/.node-version b/packages/cli/snap-tests-global/passthrough-notice/.node-version
new file mode 100644
index 0000000000..c107424776
--- /dev/null
+++ b/packages/cli/snap-tests-global/passthrough-notice/.node-version
@@ -0,0 +1 @@
+14.15.0
diff --git a/packages/cli/snap-tests-global/passthrough-notice/package.json b/packages/cli/snap-tests-global/passthrough-notice/package.json
new file mode 100644
index 0000000000..3c430d83a4
--- /dev/null
+++ b/packages/cli/snap-tests-global/passthrough-notice/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "passthrough-notice",
+  "packageManager": "pnpm@7.33.0",
+  "scripts": {
+    "dev": "echo PASSTHROUGH_MARKER"
+  }
+}
diff --git a/packages/cli/snap-tests-global/passthrough-notice/snap.txt b/packages/cli/snap-tests-global/passthrough-notice/snap.txt
new file mode 100644
index 0000000000..80a090f6fa
--- /dev/null
+++ b/packages/cli/snap-tests-global/passthrough-notice/snap.txt
@@ -0,0 +1,4 @@
+> vp run dev # should show passthrough notice and run script
+warn: Node 14.15.0 is below the Vite+ minimum (20.19.0); using passthrough mode — running the project's package manager directly without loading the Vite+ CLI. Upgrade Node to restore full Vite+ functionality.
+$ pnpm run dev
+PASSTHROUGH_MARKER
diff --git a/packages/cli/snap-tests-global/passthrough-notice/steps.json b/packages/cli/snap-tests-global/passthrough-notice/steps.json
new file mode 100644
index 0000000000..fb5a058f9f
--- /dev/null
+++ b/packages/cli/snap-tests-global/passthrough-notice/steps.json
@@ -0,0 +1,5 @@
+{
+  "commands": [
+    "vp run dev # should show passthrough notice and run script"
+  ]
+}