feat: add vitePlugins() helper for conditional plugin loading by fengmk2 · Pull Request #1215 · voidzero-dev/vite-plus

fengmk2 · 2026-03-30T12:32:17Z

Summary

Add vitePlugins() helper that conditionally loads plugins based on the VP_COMMAND environment variable
Plugins load for dev, build, test, and preview commands; skipped for everything else
Set VP_COMMAND automatically in bin.ts for every vp command
Simplify defineConfig back to a plain passthrough (remove lazy field approach)
Add docs and tests for the new API

Refs vitejs/vite#22085

Usage

import { defineConfig, vitePlugins } from 'vite-plus'

// sync
export default defineConfig({
  plugins: vitePlugins(() => [fooPlugin()]),
})

// async (wrap in array — Vite's asyncFlatten handles Promise elements)
export default defineConfig({
  plugins: [
    vitePlugins(async () => {
      const { default: heavyPlugin } = await import('vite-plugin-heavy');
      return [heavyPlugin()];
    }),
  ],
})

Test plan

Unit tests pass: vp test -- packages/cli/src/__tests__/index.spec.ts (15 tests)
Snap test passes: pnpm -F vite-plus snap-test-local lazy-loading
vp check passes (format + lint)

🤖 Generated with Claude Code

netlify · 2026-03-30T12:32:26Z

✅ Deploy Preview for viteplus-preview canceled.

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

fengmk2 · 2026-03-30T12:32:32Z

feat: add vitePlugins() helper for conditional plugin loading #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.)

docs/config/index.md

cpojer · 2026-03-31T02:14:23Z

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<…>>.

docs/config/index.md

docs/config/troubleshooting.md

fengmk2 · 2026-03-31T03:29:38Z

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 · 2026-03-31T09:37:01Z

Upstream issue created here: vitejs/vite#22085

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.

Use Vite's native Promise-based plugin support via dynamic import() instead of the custom lazy field. Migrate the documentation from config/index.md to a new config/troubleshooting.md page and update the snap test to use the import().then() pattern.

Vite does not support functions or async factories in the plugins array, so there is no native way to truly lazy-load plugins. Revert the troubleshooting docs and snap test to use the vite-plus lazy field.

…ugin loading Replace the `lazy` field approach in `defineConfig` with a standalone `vitePlugins()` function that checks the `VP_COMMAND` environment variable to conditionally load plugins only for commands that need them (dev, build, test, preview). This is simpler, more explicit, and doesn't require modifying defineConfig internals. The VP_COMMAND env var is set automatically by vp for every command. Refs vitejs/vite#22085

vitePlugins() now returns [] when skipping, making it directly assignable to plugins. For async callbacks, wrap in an array since Vite's plugins field expects PluginOption[], not a bare Promise.

…ePlugins

The heavy-plugin.ts throws on import, proving the dynamic import inside vitePlugins() is never executed during vp lint.

TheAlexLichter · 2026-04-03T09:38:00Z

docs/config/troubleshooting.md

+
+export default defineConfig({
+  plugins: [
+    vitePlugins(() => [myPlugin()]),


The vitePlugins naming is a bit confusing to me. If we can somehow indicate that they are skipped for vp lint/fmt/check in the helper name that'd be nice.

Closest I come is lazyPlugins but that might be too ambiguous. Another one was viteOnlyPlugins.

fengmk2 requested review from branchseer, cpojer and leaysgur March 30, 2026 12:32

fengmk2 self-assigned this Mar 30, 2026

fengmk2 marked this pull request as ready for review March 30, 2026 12:32

fengmk2 force-pushed the how-to-use-lazy-field branch from 5adc3fd to 49d17df Compare March 30, 2026 12:34

leaysgur reviewed Mar 31, 2026

View reviewed changes

docs/config/index.md Outdated Show resolved Hide resolved

branchseer reviewed Mar 31, 2026

View reviewed changes

docs/config/index.md Outdated Show resolved Hide resolved

fengmk2 force-pushed the how-to-use-lazy-field branch from 49d17df to b3cb2f5 Compare March 31, 2026 03:08

fengmk2 commented Mar 31, 2026

View reviewed changes

docs/config/troubleshooting.md Outdated Show resolved Hide resolved

fengmk2 changed the title ~~docs: add lazy loading plugins documentation and tests~~ docs: add config troubleshooting page with lazy loading guide Mar 31, 2026

fengmk2 force-pushed the how-to-use-lazy-field branch from b3cb2f5 to 8936d0c Compare March 31, 2026 03:31

fengmk2 changed the title ~~docs: add config troubleshooting page with lazy loading guide~~ docs: add config troubleshooting page with lazy plugin loading guide Mar 31, 2026

fengmk2 marked this pull request as draft March 31, 2026 05:18

fengmk2 closed this Apr 2, 2026

fengmk2 reopened this Apr 3, 2026

fengmk2 added 5 commits April 3, 2026 14:54

docs: revert to lazy field approach for deferred plugin loading

cc8352b

Vite does not support functions or async factories in the plugins array, so there is no native way to truly lazy-load plugins. Revert the troubleshooting docs and snap test to use the vite-plus lazy field.

fix: add curly braces to satisfy eslint curly rule

71d3659

fengmk2 force-pushed the how-to-use-lazy-field branch from 8936d0c to 71d3659 Compare April 3, 2026 07:25

fengmk2 changed the title ~~docs: add config troubleshooting page with lazy plugin loading guide~~ feat: add vitePlugins() helper for conditional plugin loading Apr 3, 2026

fengmk2 added 2 commits April 3, 2026 15:31

fix: return empty array instead of undefined and wrap async in array

4a6bc99

vitePlugins() now returns [] when skipping, making it directly assignable to plugins. For async callbacks, wrap in an array since Vite's plugins field expects PluginOption[], not a bare Promise.

fix: revert vitePlugins return type to T | undefined

df26b27

fengmk2 added 5 commits April 3, 2026 15:35

test: add snap test for sync vitePlugins() usage

df1e199

refactor: rename lazy-loading-plugins snap test to vite-plugins-async

c6a609e

docs: use consistent array-wrapped syntax for both sync and async vit…

31f920c

…ePlugins

test: add snap test to verify vp lint skips plugin loading

52fd15b

test: use async import pattern in skip-on-lint snap test

45c4827

The heavy-plugin.ts throws on import, proving the dynamic import inside vitePlugins() is never executed during vp lint.

fengmk2 marked this pull request as ready for review April 3, 2026 08:17

fengmk2 added the test: e2e Auto run e2e tests label Apr 3, 2026

fengmk2 added 2 commits April 3, 2026 16:34

fix: move snap test comment inline after command

93586a8

fix: move snap test comments inline after commands

dfaae49

TheAlexLichter reviewed Apr 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add vitePlugins() helper for conditional plugin loading#1215

feat: add vitePlugins() helper for conditional plugin loading#1215
fengmk2 wants to merge 14 commits intomainfrom
how-to-use-lazy-field

fengmk2 commented Mar 30, 2026 •

edited

Loading

Uh oh!

netlify bot commented Mar 30, 2026 •

edited

Loading

Uh oh!

fengmk2 commented Mar 30, 2026

Uh oh!

leaysgur left a comment

Uh oh!

Uh oh!

cpojer commented Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

fengmk2 commented Mar 31, 2026

Uh oh!

cpojer commented Mar 31, 2026

Uh oh!

TheAlexLichter Apr 3, 2026

Uh oh!

TheAlexLichter Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

fengmk2 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Test plan

Uh oh!

netlify bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viteplus-preview canceled.

Uh oh!

fengmk2 commented Mar 30, 2026

How to use the Graphite Merge Queue

Uh oh!

leaysgur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cpojer commented Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

fengmk2 commented Mar 31, 2026

Uh oh!

cpojer commented Mar 31, 2026

Uh oh!

TheAlexLichter Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

TheAlexLichter Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

fengmk2 commented Mar 30, 2026 •

edited

Loading

netlify bot commented Mar 30, 2026 •

edited

Loading