feat(vite-plus): support lazy field in vite-plus config (#526)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Medium Risk**
> Adds new config evaluation behavior that can change when/which plugins are included, and adjusts CLI build output (new CJS artifact) and CI build ordering; mistakes here could break consumer configs or packaging.
> 
> **Overview**
> Adds a custom `defineConfig` wrapper in `vite-plus` that supports a `lazy()` field to asynchronously provide additional plugins and merges them with any existing `plugins`, working for object, promise, and function config forms.
> 
> Updates the CLI entrypoints and build to ship `define-config` for both ESM and CommonJS (emitting `define-config.cjs`), and adds thorough unit coverage for the new `lazy` behavior.
> 
> Adjusts CI build steps so `vite-plus`/`vite-plus-cli` TypeScript builds run earlier, updates the repo `vite.config.ts` to use `defineConfig`, and makes small workspace/lint script tweaks.
> 
> <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 2f8417b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Brooooooklyn

.github/actions/build-upstream/action.yml

@@ -48,6 +48,8 @@ runs:
         pnpm --filter vite build-types
         pnpm --filter=@voidzero-dev/vite-plus-core build
         pnpm --filter=@voidzero-dev/vite-plus-test build
+        pnpm --filter=vite-plus build-ts
+        pnpm --filter=vite-plus-cli build-ts
 
     # NAPI builds - only run on cache miss (slow, especially on Windows)
     # Must run before vite-plus/vite-plus-cli TypeScript builds which depend on the bindings
@@ -94,10 +96,3 @@ runs:
           packages/global/binding/index.js
           packages/global/binding/index.d.ts
         key: ${{ steps.cache-key.outputs.key }}
-
-    # Build vite-plus TypeScript after native bindings are ready
-    - name: Build vite-plus TypeScript packages
-      shell: bash
-      run: |
-        pnpm --filter=vite-plus build-ts
-        pnpm --filter=vite-plus-cli build-ts

package.json

@@ -10,7 +10,7 @@
     "install-global-cli": "pnpm --filter=vite-plus-cli copy-binding && tool install-global-cli vite",
     "install-global-cli:local": "pnpm --filter=vite-plus-cli copy-binding && tool install-global-cli vp",
     "tsgo": "tsgo -b tsconfig.json",
-    "lint": "vite lint --type-aware --type-check --threads 4",
+    "lint": "vite lint --type-aware --threads 4",
     "test": "vite test run && pnpm -r snap-test",
     "fmt": "vite fmt",
     "test:unit": "vite test run",

packages/cli/build.ts

@@ -16,9 +16,10 @@
  */
 
 import { existsSync, globSync, readdirSync, statSync } from 'node:fs';
-import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
 
 import { createBuildCommand, NapiCli } from '@napi-rs/cli';
 import { format } from 'oxfmt';
@@ -29,25 +30,36 @@ import {
   parseJsonSourceFileConfigFileContent,
   readJsonConfigFile,
   sys,
+  ModuleKind,
 } from 'typescript';
 
 const projectDir = dirname(fileURLToPath(import.meta.url));
 const TEST_PACKAGE_NAME = '@voidzero-dev/vite-plus-test';
 const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
 
-const skipNative = process.argv.includes('--skip-native');
-const skipTs = process.argv.includes('--skip-ts');
+const {
+  values: { ['skip-native']: skipNative, ['skip-ts']: skipTs },
+} = parseArgs({
+  options: {
+    ['skip-native']: { type: 'boolean', default: false },
+    ['skip-ts']: { type: 'boolean', default: false },
+  },
+  strict: false,
+});
+
 // Filter out custom flags before passing to NAPI CLI
 const napiArgs = process.argv
   .slice(2)
   .filter((arg) => arg !== '--skip-native' && arg !== '--skip-ts');
 
+if (!skipTs) {
+  await buildCli();
+}
 // Build native first - TypeScript may depend on the generated binding types
 if (!skipNative) {
   await buildNapiBinding();
 }
 if (!skipTs) {
-  await buildCli();
   await syncCorePackageExports();
   await syncTestPackageExports();
 }
@@ -106,11 +118,38 @@ async function buildCli() {
     sys,
     projectDir,
   );
+
   const options = {
     ...initialOptions,
     noEmit: false,
     outDir: join(projectDir, 'dist'),
   };
+
+  const cjsHost = createCompilerHost({
+    ...options,
+    module: ModuleKind.CommonJS,
+  });
+
+  const cjsProgram = createProgram({
+    rootNames: ['src/define-config.ts'],
+    options: {
+      ...options,
+      module: ModuleKind.CommonJS,
+    },
+    host: cjsHost,
+  });
+
+  const { diagnostics: cjsDiagnostics } = cjsProgram.emit();
+
+  if (cjsDiagnostics.length > 0) {
+    console.error(formatDiagnostics(cjsDiagnostics, cjsHost));
+    process.exit(1);
+  }
+  await rename(
+    join(projectDir, 'dist/define-config.js'),
+    join(projectDir, 'dist/define-config.cjs'),
+  );
+
   const host = createCompilerHost(options);
 
   const program = createProgram({

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

@@ -19,3 +19,125 @@ test('should keep vitest exports stable', () => {
   expect(defaultInclude).toBeDefined();
   expect(defaultBrowserPort).toBeDefined();
 });
+
+test('should support lazy loading of plugins', async () => {
+  const config = await defineConfig({
+    lazy: () => Promise.resolve({ plugins: [{ name: 'test' }] }),
+  });
+  expect(config.plugins?.length).toBe(1);
+});
+
+test('should merge lazy plugins with existing plugins', async () => {
+  const config = await defineConfig({
+    plugins: [{ name: 'existing' }],
+    lazy: () => Promise.resolve({ plugins: [{ name: 'lazy' }] }),
+  });
+  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('lazy');
+});
+
+test('should handle lazy with empty plugins array', async () => {
+  const config = await defineConfig({
+    lazy: () => Promise.resolve({ plugins: [] }),
+  });
+  expect(config.plugins?.length).toBe(0);
+});
+
+test('should handle lazy returning undefined plugins', async () => {
+  const config = await defineConfig({
+    lazy: () => Promise.resolve({}),
+  });
+  expect(config.plugins?.length).toBe(0);
+});
+
+test('should handle Promise config with lazy', async () => {
+  const config = await defineConfig(
+    Promise.resolve({
+      lazy: () => Promise.resolve({ plugins: [{ name: 'lazy-from-promise' }] }),
+    }),
+  );
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('lazy-from-promise');
+});
+
+test('should handle Promise config with lazy and existing plugins', async () => {
+  const config = await defineConfig(
+    Promise.resolve({
+      plugins: [{ name: 'existing' }],
+      lazy: () => Promise.resolve({ plugins: [{ name: 'lazy' }] }),
+    }),
+  );
+  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('lazy');
+});
+
+test('should handle Promise config without lazy', async () => {
+  const config = await defineConfig(
+    Promise.resolve({
+      plugins: [{ name: 'no-lazy' }],
+    }),
+  );
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('no-lazy');
+});
+
+test('should handle function config with lazy', async () => {
+  const configFn = defineConfig(() => ({
+    lazy: () => Promise.resolve({ plugins: [{ name: 'lazy-from-fn' }] }),
+  }));
+  expect(typeof configFn).toBe('function');
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('lazy-from-fn');
+});
+
+test('should handle function config with lazy and existing plugins', async () => {
+  const configFn = defineConfig(() => ({
+    plugins: [{ name: 'existing' }],
+    lazy: () => Promise.resolve({ plugins: [{ name: 'lazy' }] }),
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  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('lazy');
+});
+
+test('should handle function config without lazy', () => {
+  const configFn = defineConfig(() => ({
+    plugins: [{ name: 'no-lazy' }],
+  }));
+  const config = configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('no-lazy');
+});
+
+test('should handle async function config with lazy', async () => {
+  const configFn = defineConfig(async () => ({
+    lazy: () => Promise.resolve({ plugins: [{ name: 'lazy-from-async-fn' }] }),
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('lazy-from-async-fn');
+});
+
+test('should handle async function config with lazy and existing plugins', async () => {
+  const configFn = defineConfig(async () => ({
+    plugins: [{ name: 'existing' }],
+    lazy: () => Promise.resolve({ plugins: [{ name: 'lazy' }] }),
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  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('lazy');
+});
+
+test('should handle async function config without lazy', async () => {
+  const configFn = defineConfig(async () => ({
+    plugins: [{ name: 'no-lazy' }],
+  }));
+  const config = await configFn({ command: 'build', mode: 'production' });
+  expect(config.plugins?.length).toBe(1);
+  expect((config.plugins?.[0] as { name: string })?.name).toBe('no-lazy');
+});

packages/cli/src/define-config.ts

@@ -0,0 +1,70 @@
+import {
+  defineConfig as viteDefineConfig,
+  type ConfigEnv,
+} from '@voidzero-dev/vite-plus-test/config';
+
+import type { UserConfig } from './index';
+
+type ViteUserConfigFnObject = (env: ConfigEnv) => UserConfig;
+type ViteUserConfigFnPromise = (env: ConfigEnv) => Promise<UserConfig>;
+type ViteUserConfigFn = (env: ConfigEnv) => UserConfig | Promise<UserConfig>;
+type ViteUserConfigExport =
+  | UserConfig
+  | Promise<UserConfig>
+  | ViteUserConfigFnObject
+  | ViteUserConfigFnPromise
+  | ViteUserConfigFn;
+
+export function defineConfig(config: UserConfig): UserConfig;
+export function defineConfig(config: Promise<UserConfig>): Promise<UserConfig>;
+export function defineConfig(config: ViteUserConfigFnObject): ViteUserConfigFnObject;
+export function defineConfig(config: ViteUserConfigFnPromise): ViteUserConfigFnPromise;
+export function defineConfig(config: ViteUserConfigExport): ViteUserConfigExport;
+
+export function defineConfig(config: ViteUserConfigExport): ViteUserConfigExport {
+  if (typeof config === 'object') {
+    if (config instanceof Promise) {
+      return config.then((config) => {
+        if (config.lazy) {
+          return config.lazy().then(({ plugins }) =>
+            viteDefineConfig({
+              ...config,
+              plugins: [...(config.plugins || []), ...(plugins || [])],
+            }),
+          );
+        }
+        return viteDefineConfig(config);
+      });
+    } else if (config.lazy) {
+      return config.lazy().then(({ plugins }) =>
+        viteDefineConfig({
+          ...config,
+          plugins: [...(config.plugins || []), ...(plugins || [])],
+        }),
+      );
+    }
+  } else if (typeof config === 'function') {
+    return viteDefineConfig((env) => {
+      const c = config(env);
+      if (c instanceof Promise) {
+        return c.then((v) => {
+          if (v.lazy) {
+            return v
+              .lazy()
+              .then(({ plugins }) =>
+                viteDefineConfig({ ...v, plugins: [...(v.plugins || []), ...(plugins || [])] }),
+              );
+          }
+          return v;
+        });
+      }
+      if (c.lazy) {
+        return c
+          .lazy()
+          .then(({ plugins }) => ({ ...c, plugins: [...(c.plugins || []), ...(plugins || [])] }));
+      }
+      return c;
+    });
+  }
+  return viteDefineConfig(config);
+}

packages/cli/src/index.cts

@@ -2,7 +2,10 @@ const vite = require('@voidzero-dev/vite-plus-core');
 
 const vitest = require('@voidzero-dev/vite-plus-test/config');
 
+const { defineConfig } = require('./define-config');
+
 module.exports = {
   ...vite,
   ...vitest,
+  defineConfig,
 };

packages/cli/src/index.ts

@@ -1,5 +1,6 @@
-import { defineConfig } from '@voidzero-dev/vite-plus-test/config';
+import { type Plugin as VitestPlugin } from '@voidzero-dev/vite-plus-test/config';
 
+import { defineConfig } from './define-config.js';
 import type { LibUserConfig } from './lib';
 import type { FormatOptions } from './oxfmt-config';
 import type { OxlintConfig } from './oxlint-config';
@@ -17,6 +18,12 @@ declare module '@voidzero-dev/vite-plus-core' {
     lib?: LibUserConfig | LibUserConfig[];
 
     tasks?: Tasks;
+
+    // temporary solution to load plugins lazily
+    // We need to support this in the upstream vite
+    lazy?: () => Promise<{
+      plugins?: VitestPlugin[];
+    }>;
   }
 }