Skip to content

Commit 7009afb

Browse files
committed
docs: move plugin factory docs to guide troubleshooting page
Address review feedback from @cpojer: - Merge into the single existing troubleshooting page instead of adding a separate config troubleshooting page - Remove the VP_COMMAND implementation detail note (not useful to users)
1 parent 509c32a commit 7009afb

File tree

3 files changed

+31
-39
lines changed

3 files changed

+31
-39
lines changed

docs/.vitepress/config.mts

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,6 @@ export default extendConfig(
166166
{ text: 'Build', link: '/config/build' },
167167
{ text: 'Pack', link: '/config/pack' },
168168
{ text: 'Staged', link: '/config/staged' },
169-
{ text: 'Troubleshooting', link: '/config/troubleshooting' },
170169
],
171170
},
172171
],

docs/config/troubleshooting.md

Lines changed: 0 additions & 38 deletions
This file was deleted.

docs/guide/troubleshooting.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,37 @@ export default defineConfig({
8989
});
9090
```
9191

92+
## Slow config loading caused by heavy plugins
93+
94+
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.
95+
96+
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:
97+
98+
```ts
99+
import { defineConfig } from 'vite-plus';
100+
101+
export default defineConfig({
102+
plugins: () => [myPlugin()],
103+
});
104+
```
105+
106+
For heavy plugins that should be lazily imported, combine with dynamic `import()`:
107+
108+
```ts
109+
import { defineConfig } from 'vite-plus';
110+
111+
export default defineConfig({
112+
plugins: async () => {
113+
const { default: heavyPlugin } = await import('vite-plugin-heavy');
114+
return [heavyPlugin()];
115+
},
116+
});
117+
```
118+
119+
::: warning
120+
The plugins factory requires `defineConfig` from `vite-plus`, not from `vite`. Vite's native `defineConfig` does not support factory functions for the `plugins` field.
121+
:::
122+
92123
## Asking for Help
93124

94125
If you are stuck, please reach out:

0 commit comments

Comments
 (0)