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

[fengmk2]

Summary

Extend defineConfig so the plugins field accepts factory functions 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

Usage

import { defineConfig } from 'vite-plus'

// sync factory — plugin construction deferred
export default defineConfig({
  plugins: () => [fooPlugin()],
})

// async factory — both import and construction deferred
export default defineConfig({
  plugins: async () => {
    const { default: heavyPlugin } = await import('vite-plugin-heavy');
    return [heavyPlugin()];
  },
})

// plain array — still works as before
export default defineConfig({
  plugins: [fooPlugin()],
})

How it works

• bin.ts sets VP_COMMAND env var from the CLI command argument
• defineConfig checks if plugins is a function; if so, only calls it when VP_COMMAND is a vite command
• For async factories, the returned Promise is wrapped in an array — Vite's asyncFlatten resolves it during plugin pipeline

Test plan

• Unit tests pass: 31 tests covering factory patterns, PluginOption compatibility, and vitest plugin hooks
• Snap tests pass: sync build, async build, and lint-skips-plugins
• vp check passes (format + lint)

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes how vite.config.ts plugins are resolved based on the running vp command, which could affect plugin execution order/availability across build/test/dev vs lint/fmt/check paths. Adds VP_COMMAND env injection in both JS and Rust CLI flows, so regressions would show up as incorrect plugin loading in synthesized commands (e.g. vp run).

Overview
Adds lazy plugin loading to vite-plus defineConfig by allowing plugins to be a sync/async factory function; the factory is executed only for Vite commands (dev/build/test/preview) and skipped for non-Vite commands to reduce config-load overhead.

The CLI now sets/injects VP_COMMAND (JS bin.ts, and Rust resolver for synthesized subcommands) so factory decisions remain correct even when commands are executed via vp run. Includes expanded unit coverage, new snapshot fixtures validating sync/async factories (including Vitest configureVitest) and that plugins are not loaded during vp lint, plus a small Windows snapshot-stabilization tweak and updated troubleshooting docs.

^{Reviewed by Cursor Bugbot for commit ca6266c. Configure here.}

[netlify]

✅ Deploy Preview for viteplus-preview canceled.

Name	Link
🔨 Latest commit	ca6266c
🔍 Latest deploy log	https://app.netlify.com/projects/viteplus-preview/deploys/69d7a03b34c2bd00080885f8

[fengmk2]

• feat: extend defineConfig to support lazy plugin loading via factory functions #1215 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label auto-merge to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[leaysgur]

I have no objection to recommending this method as a current workaround. 👌🏻

(However, I cannot judge whether this is the best approach, as I do not know the background behind why this lazy was introduced.)

[cpojer]

I'm really not a fan of the lazy attribute and I don't think we should recommend it. It would be better to make the plugins field either an array or a function that returns Promise<Array<…>>.

[fengmk2]

I'm really not a fan of the lazy attribute and I don't think we should recommend it. It would be better to make the plugins field either an array or a function that returns Promise<Array<…>>.

This needs to be resolved on the Vite side. I think Vite+ should not change the meaning of fields defined by Vite. @sapphi-red

[cpojer]

Upstream issue created here: vitejs/vite#22085

[cpojer]

I don't really follow, why do we need to add a new function to wrap plugins instead of redefining the plugin type from plugins: Array<Plugin> to plugins: Array<Plugin> | () => Promise<Array<Plugin>>?

[TheAlexLichter]

I don't really follow, why do we need to add a new function to wrap plugins instead of redefining the plugin type from plugins: Array<Plugin> to plugins: Array<Plugin> | () => Promise<Array<Plugin>>?

That only works if we'd "guarantee" there are no plugins that can influence the behavior of vp lint, vp fmt etc.

[cpojer]

For now, that's the expectation, yes.

[TheAlexLichter]

I think then we can also wrap the whole function (as long there is no type mismatch or we alter the allowed types of plugins).

[cpojer]

It's beautiful. From a UX perspective, I love it. I don't know if there are any remaining concerns from the Vite side, cc @sapphi-red if you don't mind signing off on this 🙇‍♂️

[fengmk2]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ca6266c. Configure here.}