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

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>

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

@@ -0,0 +1,8 @@
+export default function myLazyPlugin() {
+  return {
+    name: 'my-lazy-plugin',
+    transformIndexHtml(html: string) {
+      return html.replace('</body>', '<!-- lazy-plugin-injected --></body>');
+    },
+  };
+}

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

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

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

@@ -0,0 +1,3 @@
+> vp build
+> cat dist/index.html | grep 'lazy-plugin-injected' # async vitePlugins() should apply plugins during build
+  <!-- lazy-plugin-injected --></body>

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

@@ -0,0 +1,9 @@
+{
+  "commands": [
+    {
+      "command": "vp build",
+      "ignoreOutput": true
+    },
+    "cat dist/index.html | grep 'lazy-plugin-injected' # async vitePlugins() should apply plugins during build"
+  ]
+}

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

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

packages/cli/snap-tests/vite-plugins-run-build/index.html

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

packages/cli/snap-tests/vite-plugins-run-build/my-plugin.ts

@@ -0,0 +1,8 @@
+export default function myPlugin() {
+  return {
+    name: 'my-run-build-plugin',
+    transformIndexHtml(html: string) {
+      return html.replace('</body>', '<!-- run-build-plugin-injected --></body>');
+    },
+  };
+}

packages/cli/snap-tests/vite-plugins-run-build/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "vite-plugins-run-build-test",
+  "private": true,
+  "scripts": {
+    "build-task": "vp build"
+  }
+}

packages/cli/snap-tests/vite-plugins-run-build/snap.txt

@@ -0,0 +1,3 @@
+> vp run build-task
+> cat dist/index.html | grep 'run-build-plugin-injected' # vp run build should load plugins from factory
+  <!-- run-build-plugin-injected --></body>

packages/cli/snap-tests/vite-plugins-run-build/steps.json

@@ -0,0 +1,9 @@
+{
+  "commands": [
+    {
+      "command": "vp run build-task",
+      "ignoreOutput": true
+    },
+    "cat dist/index.html | grep 'run-build-plugin-injected' # vp run build should load plugins from factory"
+  ]
+}

packages/cli/snap-tests/vite-plugins-run-build/vite.config.ts

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

packages/cli/snap-tests/vite-plugins-skip-on-lint/heavy-plugin.ts

@@ -0,0 +1,5 @@
+throw new Error('Plugins should not be loaded during lint');
+
+export default function heavyPlugin() {
+  return { name: 'heavy-plugin' };
+}

packages/cli/snap-tests/vite-plugins-skip-on-lint/package.json

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

packages/cli/snap-tests/vite-plugins-skip-on-lint/snap.txt

@@ -0,0 +1,3 @@
+> vp lint src/ # vp lint should not load plugins (heavy-plugin.ts throws if imported)
+Found 0 warnings and 0 errors.
+Finished in <variable>ms on 1 file with <variable> rules using <variable> threads.

packages/cli/snap-tests/vite-plugins-skip-on-lint/src/index.ts

@@ -0,0 +1 @@
+export const foo = 'bar';

packages/cli/snap-tests/vite-plugins-skip-on-lint/steps.json

@@ -0,0 +1,5 @@
+{
+  "commands": [
+    "vp lint src/ # vp lint should not load plugins (heavy-plugin.ts throws if imported)"
+  ]
+}

packages/cli/snap-tests/vite-plugins-skip-on-lint/vite.config.ts

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

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

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

packages/cli/snap-tests/vite-plugins-sync/my-plugin.ts

@@ -0,0 +1,8 @@
+export default function mySyncPlugin() {
+  return {
+    name: 'my-sync-plugin',
+    transformIndexHtml(html: string) {
+      return html.replace('</body>', '<!-- sync-plugin-injected --></body>');
+    },
+  };
+}

packages/cli/snap-tests/vite-plugins-sync/package.json

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

packages/cli/snap-tests/vite-plugins-sync/snap.txt

@@ -0,0 +1,3 @@
+> vp build
+> cat dist/index.html | grep 'sync-plugin-injected' # sync vitePlugins() should apply plugins during build
+  <!-- sync-plugin-injected --></body>

packages/cli/snap-tests/vite-plugins-sync/steps.json

@@ -0,0 +1,9 @@
+{
+  "commands": [
+    {
+      "command": "vp build",
+      "ignoreOutput": true
+    },
+    "cat dist/index.html | grep 'sync-plugin-injected' # sync vitePlugins() should apply plugins during build"
+  ]
+}

packages/cli/snap-tests/vite-plugins-sync/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite-plus';
+
+import mySyncPlugin from './my-plugin';
+
+export default defineConfig({
+  plugins: () => [mySyncPlugin()],
+});