docs: add lazy loading plugins documentation and tests

fengmk2 · fengmk2 · commit 49d17dfd8a79 · 2026-03-30T20:34:09.000+08:00
Document the `lazy` field in config page with usage examples showing
how to defer heavy plugin imports using async/await dynamic imports.
Add unit tests for async/await lazy loading patterns and a snap test
that verifies lazy-loaded plugins are applied during vp build.
diff --git a/docs/config/index.md b/docs/config/index.md
@@ -29,3 +29,66 @@ Vite+ extends the basic Vite configuration with these additions:
 - [`run`](/config/run) for Vite Task
 - [`pack`](/config/pack) for tsdown
 - [`staged`](/config/staged) for staged-file checks
+
+## Lazy Loading 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.
+
+The `lazy` field solves this by letting you defer plugin loading into an async function. Plugins provided through `lazy` are only resolved when actually needed:
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  lazy: async () => {
+    const { default: myHeavyPlugins } = await import('./my-heavy-plugins');
+    return { plugins: myHeavyPlugins };
+  },
+});
+```
+
+### Type Signature
+
+```ts
+lazy?: () => Promise<{
+  plugins?: Plugin[];
+}>;
+```
+
+### Merging with Existing Plugins
+
+Plugins returned from `lazy` are appended after any plugins already in the `plugins` array. This lets you keep lightweight plugins inline and defer only the expensive ones:
+
+```ts
+import { defineConfig } from 'vite-plus';
+import lightPlugin from 'vite-plugin-light';
+
+export default defineConfig({
+  plugins: [lightPlugin()],
+  lazy: async () => {
+    const { default: heavyPlugin } = await import('vite-plugin-heavy');
+    return { plugins: [heavyPlugin()] };
+  },
+});
+```
+
+The resulting plugin order is: `[lightPlugin(), heavyPlugin()]`.
+
+### Function Config
+
+`lazy` also works with function-style and async function-style configs:
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig(async () => ({
+  lazy: async () => {
+    const { default: heavyPlugin } = await import('vite-plugin-heavy');
+    return { plugins: [heavyPlugin()] };
+  },
+}));
+```
+
+::: info
+The `lazy` field is a temporary Vite+ extension. We plan to support this in upstream Vite in the future.
+:::
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/index.html b/packages/cli/snap-tests/lazy-loading-plugins/index.html
@@ -0,0 +1,8 @@
+<!doctype html>
+<html>
+  <body>
+    <script type="module">
+      console.log('hello');
+    </script>
+  </body>
+</html>
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/my-plugin.ts b/packages/cli/snap-tests/lazy-loading-plugins/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>');
+    },
+  };
+}
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/package.json b/packages/cli/snap-tests/lazy-loading-plugins/package.json
@@ -0,0 +1,4 @@
+{
+  "name": "lazy-loading-plugins-test",
+  "private": true
+}
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/snap.txt b/packages/cli/snap-tests/lazy-loading-plugins/snap.txt
@@ -0,0 +1,4 @@
+> # Test that plugins loaded via lazy field are applied during build
+> vp build
+> cat dist/index.html | grep 'lazy-plugin-injected'
+  <!-- lazy-plugin-injected --></body>
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/steps.json b/packages/cli/snap-tests/lazy-loading-plugins/steps.json
@@ -0,0 +1,10 @@
+{
+  "commands": [
+    "# Test that plugins loaded via lazy field are applied during build",
+    {
+      "command": "vp build",
+      "ignoreOutput": true
+    },
+    "cat dist/index.html | grep 'lazy-plugin-injected'"
+  ]
+}
diff --git a/packages/cli/snap-tests/lazy-loading-plugins/vite.config.ts b/packages/cli/snap-tests/lazy-loading-plugins/vite.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  lazy: async () => {
+    const { default: myLazyPlugin } = await import('./my-plugin');
+    return { plugins: [myLazyPlugin()] };
+  },
+});
diff --git a/packages/cli/src/__tests__/index.spec.ts b/packages/cli/src/__tests__/index.spec.ts
@@ -141,3 +141,63 @@ test('should handle async function config without lazy', async () => {
   expect(config.plugins?.length).toBe(1);
   expect((config.plugins?.[0] as { name: string })?.name).toBe('no-lazy');
 });
+
+test('should support async/await lazy loading of plugins', async () => {
+  const config = await defineConfig({
+    lazy: async () => {
+      const plugins = [{ name: 'async-lazy' }];
+      return { plugins };
+    },
+  });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('async-lazy');
+});
+
+test('should merge async/await lazy plugins with existing plugins', async () => {
+  const config = await defineConfig({
+    plugins: [{ name: 'existing' }],
+    lazy: async () => {
+      const plugins = [{ name: 'async-lazy' }];
+      return { plugins };
+    },
+  });
+  expect(config.plugins?.length).toBe(2);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('existing');
+  expect((config.plugins?.[1] as { name: string })?.name).toBe('async-lazy');
+});
+
+test('should support async/await lazy with dynamic import pattern', async () => {
+  const config = await defineConfig({
+    lazy: async () => {
+      // simulates: const { default: plugin } = await import('heavy-plugin')
+      const plugin = await Promise.resolve({ name: 'dynamic-import-plugin' });
+      return { plugins: [plugin] };
+    },
+  });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('dynamic-import-plugin');
+});
+
+test('should support async/await lazy in async function config', async () => {
+  const configFn = defineConfig(async () => ({
+    lazy: async () => {
+      const plugins = [{ name: 'async-fn-async-lazy' }];
+      return { plugins };
+    },
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('async-fn-async-lazy');
+});
+
+test('should support async/await lazy in sync function config', async () => {
+  const configFn = defineConfig(() => ({
+    lazy: async () => {
+      const plugins = [{ name: 'sync-fn-async-lazy' }];
+      return { plugins };
+    },
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('sync-fn-async-lazy');
+});

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "name": "lazy-loading-plugins-test",
 +  "private": true
 +}