feat: add lazyPlugins() helper for conditional plugin loading (#1215)

## Summary

Add `lazyPlugins()` helper that conditionally loads plugins based on the
`VP_COMMAND` environment variable. Plugins load for vite commands
(`dev`, `build`, `test`, `preview`) and when `VP_COMMAND` is unset
(e.g., running vitest directly or via VS Code extension). Skipped for
non-vite commands (`lint`, `fmt`, `check`, etc.).

Refs vitejs/vite#22085

### Usage

```ts
import { defineConfig, lazyPlugins } from 'vite-plus'

// sync
export default defineConfig({
  plugins: lazyPlugins(() => [fooPlugin()]),
})

// async with dynamic import
export default defineConfig({
  plugins: lazyPlugins(async () => {
    const { default: heavyPlugin } = await import('vite-plugin-heavy');
    return [heavyPlugin()];
  }),
})
```

### How it works

- `bin.ts` sets `VP_COMMAND` env var from the CLI command argument
- Rust resolver injects `VP_COMMAND` into child process envs for
synthesized subcommands (fixes `vp run build` case)
- `lazyPlugins` checks `VP_COMMAND` — executes callback for vite
commands, returns `undefined` otherwise
- Async callbacks have their Promise wrapped in an array internally for
Vite's `asyncFlatten`

## Test plan

- [x] Unit tests: 30 tests — lazyPlugins behavior, type compatibility
with `plugins` field, defineConfig compatibility, vitest plugin hooks
- [x] Snap tests: 6 cases — sync build, async build, vitest plugin,
skip-on-lint, `vp run build`, `vp run lint`
- [x] `vp check` passes (format + lint)
- [x] Windows CI: forward-slash path normalization fix for snap test
stability

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: fengmk2

docs/config/index.md

@@ -28,4 +28,4 @@ Vite+ extends the basic Vite configuration with these additions:
 - [`test`](/config/test) for Vitest
 - [`run`](/config/run) for Vite Task
 - [`pack`](/config/pack) for tsdown
-- [`staged`](/config/staged) for staged-file checks
+- [`staged`](/config/staged) for staged-file checks

docs/guide/troubleshooting.md

@@ -89,6 +89,34 @@ export default defineConfig({
 });
 ```
 
+## Slow config loading caused by heavy plugins
+
+When `vite.config.ts` imports heavy plugins at the top level, every `import` is evaluated eagerly, even for commands like `vp lint` or `vp fmt` that don't need those plugins. This can make config loading noticeably slow.
+
+Use `lazyPlugins` to wrap plugin loading. Plugins are only loaded for commands that need them (`dev`, `build`, `test`, `preview`), and skipped for everything else:
+
+```ts
+import { defineConfig, lazyPlugins } from 'vite-plus';
+import myPlugin from 'vite-plugin-foo';
+
+export default defineConfig({
+  plugins: lazyPlugins(() => [myPlugin()]),
+});
+```
+
+For heavy plugins that should be lazily imported, combine with dynamic `import()`:
+
+```ts
+import { defineConfig, lazyPlugins } from 'vite-plus';
+
+export default defineConfig({
+  plugins: lazyPlugins(async () => {
+    const { default: heavyPlugin } = await import('vite-plugin-heavy');
+    return [heavyPlugin()];
+  }),
+});
+```
+
 ## Asking for Help
 
 If you are stuck, please reach out:

packages/cli/binding/src/cli/resolver.rs

@@ -68,6 +68,22 @@ impl SubcommandResolver {
         resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
         envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
         cwd: &Arc<AbsolutePath>,
+    ) -> anyhow::Result<ResolvedSubcommand> {
+        let command_name = subcommand.command_name();
+        let mut resolved = self.resolve_inner(subcommand, resolved_vite_config, envs, cwd).await?;
+        // Inject VP_COMMAND so that defineConfig's plugin factory knows which command is running,
+        // even when the subcommand is synthesized inside `vp run`.
+        let envs = Arc::make_mut(&mut resolved.envs);
+        envs.insert(Arc::from(OsStr::new("VP_COMMAND")), Arc::from(OsStr::new(command_name)));
+        Ok(resolved)
+    }
+
+    async fn resolve_inner(
+        &self,
+        subcommand: SynthesizableSubcommand,
+        resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
+        envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
+        cwd: &Arc<AbsolutePath>,
     ) -> anyhow::Result<ResolvedSubcommand> {
         match subcommand {
             SynthesizableSubcommand::Lint { mut args } => {

packages/cli/binding/src/cli/types.rs

@@ -102,6 +102,24 @@ pub enum SynthesizableSubcommand {
     },
 }
 
+impl SynthesizableSubcommand {
+    /// Return the command name string for use in `VP_COMMAND` env var.
+    pub(super) fn command_name(&self) -> &'static str {
+        match self {
+            Self::Lint { .. } => "lint",
+            Self::Fmt { .. } => "fmt",
+            Self::Build { .. } => "build",
+            Self::Test { .. } => "test",
+            Self::Pack { .. } => "pack",
+            Self::Dev { .. } => "dev",
+            Self::Preview { .. } => "preview",
+            Self::Doc { .. } => "doc",
+            Self::Install { .. } => "install",
+            Self::Check { .. } => "check",
+        }
+    }
+}
+
 /// Top-level CLI argument parser for vite-plus.
 #[derive(Debug, Parser)]
 #[command(name = "vp", disable_help_subcommand = true)]

packages/cli/snap-tests/vite-plugins-async-test/my-vitest-plugin.ts

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export default function myVitestPlugin() {
+  return {
+    name: 'my-vitest-plugin',
+    configureVitest() {
+      fs.writeFileSync(
+        path.join(import.meta.dirname, '.vitest-plugin-loaded'),
+        'configureVitest hook executed',
+      );
+    },
+  };
+}

packages/cli/snap-tests/vite-plugins-async-test/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "vite-plugins-async-test",
+  "private": true
+}

packages/cli/snap-tests/vite-plugins-async-test/snap.txt

@@ -0,0 +1,10 @@
+> vp test # async plugins factory should load vitest plugin with configureVitest hook
+ RUN  <cwd>
+
+ ✓ src/index.test.ts (1 test) <variable>ms
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  <date>
+   Duration  <variable>ms (transform <variable>ms, setup <variable>ms, import <variable>ms, tests <variable>ms, environment <variable>ms)
+

packages/cli/snap-tests/vite-plugins-async-test/src/index.test.ts

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { expect, onTestFinished, test } from '@voidzero-dev/vite-plus-test';
+
+test('async plugin factory should load vitest plugin with configureVitest hook', () => {
+  const markerPath = path.join(import.meta.dirname, '..', '.vitest-plugin-loaded');
+  onTestFinished(() => {
+    fs.rmSync(markerPath, { force: true });
+  });
+  expect(fs.existsSync(markerPath)).toBe(true);
+  expect(fs.readFileSync(markerPath, 'utf-8')).toBe('configureVitest hook executed');
+});

packages/cli/snap-tests/vite-plugins-async-test/steps.json

@@ -0,0 +1,5 @@
+{
+  "commands": [
+    "vp test # async plugins factory should load vitest plugin with configureVitest hook"
+  ]
+}

packages/cli/snap-tests/vite-plugins-async-test/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig, lazyPlugins } from 'vite-plus';
+
+export default defineConfig({
+  plugins: lazyPlugins(async () => {
+    const { default: myVitestPlugin } = await import('./my-vitest-plugin');
+    return [myVitestPlugin()];
+  }),
+});