feat: extend defineConfig to support lazy plugin loading via factory functions

The `plugins` field in `defineConfig` now accepts factory functions
(`() => PluginOption[]` or `async () => Promise<PluginOption[]>`)
in addition to the standard `PluginOption[]` array.

The factory is only called for vite commands (dev, build, test, preview)
and skipped for non-vite commands (lint, fmt, check, etc.), avoiding
unnecessary plugin loading overhead. When VP_COMMAND is unset (e.g.,
running vitest directly or via VS Code extension), plugins load by default.

VP_COMMAND is set automatically by `vp` in bin.ts and injected into
child process envs by the Rust resolver for synthesized subcommands.

Refs vitejs/vite#22085

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,37 @@ 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.
+
+Pass a factory function to `plugins` in `defineConfig` to defer plugin loading. The factory is only called for commands that need plugins (`dev`, `build`, `test`, `preview`), and skipped for everything else:
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  plugins: () => [myPlugin()],
+});
+```
+
+For heavy plugins that should be lazily imported, combine with dynamic `import()`:
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  plugins: async () => {
+    const { default: heavyPlugin } = await import('vite-plugin-heavy');
+    return [heavyPlugin()];
+  },
+});
+```
+
+::: warning
+The plugins factory requires `defineConfig` from `vite-plus`, not from `vite`. Vite's native `defineConfig` does not support factory functions for the `plugins` field.
+:::
+
 ## Asking for Help
 
 If you are stuck, please reach out:

packages/cli/binding/src/cli.rs

@@ -123,6 +123,24 @@ pub enum SynthesizableSubcommand {
     },
 }
 
+impl SynthesizableSubcommand {
+    /// Return the command name string for use in `VP_COMMAND` env var.
+    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)]
@@ -233,6 +251,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/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,11 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { expect, 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');
+  expect(fs.existsSync(markerPath)).toBe(true);
+  expect(fs.readFileSync(markerPath, 'utf-8')).toBe('configureVitest hook executed');
+  fs.unlinkSync(markerPath);
+});

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 } from 'vite-plus';
+
+export default defineConfig({
+  plugins: async () => {
+    const { default: myVitestPlugin } = await import('./my-vitest-plugin');
+    return [myVitestPlugin()];
+  },
+});

packages/cli/snap-tests/vite-plugins-async/index.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<html>
+  <body>
+    <script type="module">
+      console.log('hello');
+    </script>
+  </body>
+</html>