feat: extend defineConfig plugins to accept factory functions

Replace the standalone vitePlugins() helper with built-in support
in defineConfig for plugins factory functions. The plugins field
now accepts () => 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.

Refs vitejs/vite#22085

Author: fengmk2

docs/config/troubleshooting.md

@@ -6,37 +6,29 @@ Use this page when your Vite+ configuration is not behaving the way you expect.
 
 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 the `vitePlugins()` helper to conditionally load plugins. It checks which `vp` command is running and skips plugin loading for commands that don't need them (like `lint`, `fmt`, `check`):
+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, vitePlugins } from 'vite-plus';
-
-import myPlugin from 'vite-plugin-foo';
+import { defineConfig } from 'vite-plus';
 
 export default defineConfig({
-  plugins: [
-    vitePlugins(() => [myPlugin()]),
-  ],
+  plugins: () => [myPlugin()],
 });
 ```
 
 For heavy plugins that should be lazily imported, combine with dynamic `import()`:
 
 ```ts
-import { defineConfig, vitePlugins } from 'vite-plus';
+import { defineConfig } from 'vite-plus';
 
 export default defineConfig({
-  plugins: [
-    vitePlugins(async () => {
-      const { default: heavyPlugin } = await import('vite-plugin-heavy');
-      return [heavyPlugin()];
-    }),
-  ],
+  plugins: async () => {
+    const { default: heavyPlugin } = await import('vite-plugin-heavy');
+    return [heavyPlugin()];
+  },
 });
 ```
 
-Plugins load for `dev`, `build`, `test`, and `preview`. They are skipped for `lint`, `fmt`, `check`, and other commands that don't need them.
-
 ::: info
-`vitePlugins()` works by checking the `VP_COMMAND` environment variable, which is automatically set by `vp` for every command.
+The plugins factory works by checking the `VP_COMMAND` environment variable, which is automatically set by `vp` for every command.
 :::

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

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

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

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

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

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

packages/cli/src/__tests__/index.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, expect, test } from '@voidzero-dev/vite-plus-test';
+import { afterEach, beforeEach, expect, test, vi } from '@voidzero-dev/vite-plus-test';
 
 import {
   configDefaults,
@@ -8,7 +8,6 @@ import {
   defaultBrowserPort,
   defineConfig,
   defineProject,
-  vitePlugins,
 } from '../index.js';
 
 let originalVpCommand: string | undefined;
@@ -28,58 +27,176 @@ afterEach(() => {
 test('should keep vitest exports stable', () => {
   expect(defineConfig).toBeTypeOf('function');
   expect(defineProject).toBeTypeOf('function');
-  expect(vitePlugins).toBeTypeOf('function');
   expect(configDefaults).toBeDefined();
   expect(coverageConfigDefaults).toBeDefined();
   expect(defaultExclude).toBeDefined();
   expect(defaultInclude).toBeDefined();
   expect(defaultBrowserPort).toBeDefined();
 });
 
-test('vitePlugins returns undefined when VP_COMMAND is unset', () => {
-  delete process.env.VP_COMMAND;
-  const result = vitePlugins(() => [{ name: 'test' }]);
-  expect(result).toBeUndefined();
-});
-
-test('vitePlugins returns undefined when VP_COMMAND is empty string', () => {
-  process.env.VP_COMMAND = '';
-  const result = vitePlugins(() => [{ name: 'test' }]);
-  expect(result).toBeUndefined();
+test('defineConfig passes through plain plugins array', () => {
+  process.env.VP_COMMAND = 'build';
+  const config = defineConfig({
+    plugins: [{ name: 'test-plugin' }],
+  });
+  expect(config.plugins?.length).toBe(1);
 });
 
 test.each(['dev', 'build', 'test', 'preview'])(
-  'vitePlugins executes callback when VP_COMMAND is %s',
+  'defineConfig executes sync plugins factory when VP_COMMAND is %s',
   (cmd) => {
     process.env.VP_COMMAND = cmd;
-    const result = vitePlugins(() => [{ name: 'my-plugin' }]);
-    expect(result).toEqual([{ name: 'my-plugin' }]);
+    const config = defineConfig({
+      plugins: () => [{ name: 'factory-plugin' }],
+    });
+    expect(config.plugins?.length).toBe(1);
+    expect((config.plugins?.[0] as { name: string })?.name).toBe('factory-plugin');
+  },
+);
+
+test.each(['dev', 'build', 'test', 'preview'])(
+  'defineConfig executes async plugins factory when VP_COMMAND is %s',
+  async (cmd) => {
+    process.env.VP_COMMAND = cmd;
+    const config = defineConfig({
+      plugins: async () => {
+        const plugin = await Promise.resolve({ name: 'async-factory-plugin' });
+        return [plugin];
+      },
+    });
+    // Async factory wraps the promise in an array for asyncFlatten
+    expect(config.plugins?.length).toBe(1);
+    const resolved = await (config.plugins?.[0] as Promise<{ name: string }[]>);
+    expect(resolved.length).toBe(1);
+    expect(resolved[0].name).toBe('async-factory-plugin');
   },
 );
 
 test.each(['lint', 'fmt', 'check', 'pack', 'install', 'run'])(
-  'vitePlugins returns undefined when VP_COMMAND is %s',
+  'defineConfig skips plugins factory when VP_COMMAND is %s',
   (cmd) => {
     process.env.VP_COMMAND = cmd;
-    const result = vitePlugins(() => [{ name: 'my-plugin' }]);
-    expect(result).toBeUndefined();
+    const factoryFn = vi.fn(() => [{ name: 'should-not-load' }]);
+    const config = defineConfig({
+      plugins: factoryFn,
+    });
+    expect(factoryFn).not.toHaveBeenCalled();
+    expect(config.plugins?.length).toBe(0);
   },
 );
 
-test('vitePlugins supports async callback', async () => {
+test('defineConfig skips plugins factory when VP_COMMAND is unset', () => {
+  delete process.env.VP_COMMAND;
+  const factoryFn = vi.fn(() => [{ name: 'should-not-load' }]);
+  const config = defineConfig({
+    plugins: factoryFn,
+  });
+  expect(factoryFn).not.toHaveBeenCalled();
+  expect(config.plugins?.length).toBe(0);
+});
+
+test('defineConfig handles function config with plugins factory', () => {
+  process.env.VP_COMMAND = 'build';
+  const configFn = defineConfig(() => ({
+    plugins: () => [{ name: 'fn-factory-plugin' }],
+  }));
+  const config = configFn({ command: 'build', mode: 'production' });
+  const plugins = config.plugins as { name: string }[];
+  expect(plugins?.length).toBe(1);
+  expect(plugins?.[0]?.name).toBe('fn-factory-plugin');
+});
+
+test('defineConfig handles async function config with plugins factory', async () => {
   process.env.VP_COMMAND = 'build';
-  const result = vitePlugins(async () => {
-    const plugin = await Promise.resolve({ name: 'async-plugin' });
-    return [plugin];
+  const configFn = defineConfig(async () => ({
+    plugins: () => [{ name: 'async-fn-factory-plugin' }],
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  const plugins = config.plugins as { name: string }[];
+  expect(plugins?.length).toBe(1);
+  expect(plugins?.[0]?.name).toBe('async-fn-factory-plugin');
+});
+
+test('defineConfig handles Promise config with plugins factory', async () => {
+  process.env.VP_COMMAND = 'build';
+  const config = await defineConfig(
+    Promise.resolve({
+      plugins: () => [{ name: 'promise-factory-plugin' }],
+    }),
+  );
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('promise-factory-plugin');
+});
+
+// Vite/Vitest PluginOption compatibility tests
+// PluginOption = Thenable<Plugin | { name: string } | false | null | undefined | PluginOption[]>
+
+test('defineConfig supports Plugin objects in plugins array', () => {
+  const config = defineConfig({
+    plugins: [{ name: 'plugin-a' }, { name: 'plugin-b' }],
+  });
+  expect(config.plugins?.length).toBe(2);
+});
+
+test('defineConfig supports falsy values in plugins array', () => {
+  const config = defineConfig({
+    plugins: [{ name: 'real-plugin' }, false, null, undefined],
+  });
+  expect(config.plugins?.length).toBe(4);
+});
+
+test('defineConfig supports nested plugin arrays', () => {
+  const config = defineConfig({
+    plugins: [[{ name: 'nested-a' }, { name: 'nested-b' }], { name: 'top-level' }],
+  });
+  expect(config.plugins?.length).toBe(2);
+});
+
+test('defineConfig supports Promise<Plugin> in plugins array', () => {
+  const config = defineConfig({
+    plugins: [Promise.resolve({ name: 'async-plugin' })],
   });
-  expect(result).toBeInstanceOf(Promise);
-  expect(await result).toEqual([{ name: 'async-plugin' }]);
+  expect(config.plugins?.length).toBe(1);
 });
 
-test('vitePlugins returns undefined for async callback when skipped', () => {
-  process.env.VP_COMMAND = 'lint';
-  const result = vitePlugins(async () => {
-    return [{ name: 'async-plugin' }];
+test('defineConfig supports mixed PluginOption types in array', () => {
+  const config = defineConfig({
+    plugins: [
+      { name: 'sync-plugin' },
+      false,
+      Promise.resolve({ name: 'promised-plugin' }),
+      [{ name: 'nested-plugin' }],
+      null,
+      undefined,
+    ],
   });
-  expect(result).toBeUndefined();
+  expect(config.plugins?.length).toBe(6);
+});
+
+test('defineConfig supports empty plugins array', () => {
+  const config = defineConfig({
+    plugins: [],
+  });
+  expect(config.plugins?.length).toBe(0);
+});
+
+test('defineConfig supports config without plugins', () => {
+  const config = defineConfig({});
+  expect(config.plugins).toBeUndefined();
+});
+
+test('defineConfig supports function config with plain plugins array', () => {
+  const configFn = defineConfig(() => ({
+    plugins: [{ name: 'fn-plugin' }],
+  }));
+  const config = configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+});
+
+test('defineConfig supports async function config with plain plugins array', async () => {
+  const configFn = defineConfig(async () => ({
+    plugins: [{ name: 'async-fn-plugin' }],
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
 });