docs: add some notes/deprecations for vite hooks

danielroe · danielroe · commit 2c6912d2f83d · 2025-10-25T15:38:17.000+09:00
diff --git a/docs/2.guide/4.recipes/2.vite-plugin.md b/docs/2.guide/4.recipes/2.vite-plugin.md
@@ -63,3 +63,26 @@ import config from '~/data/hello.yaml'
 ```
 
 ::
+
+## Using Vite Plugins in Nuxt Modules
+
+If you're developing a Nuxt module and need to add Vite plugins, you should use the [`addVitePlugin`](/docs/4.x/api/kit/builder#addviteplugin) utility:
+
+```ts [modules/my-module.ts]
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+import yaml from '@rollup/plugin-yaml'
+
+export default defineNuxtModule({
+  setup () {
+    addVitePlugin(yaml())
+  },
+})
+```
+
+::important
+If you're writing code that needs to access resolved Vite configuration, you should use the `config` and `configResolved` hooks _within_ your Vite plugin, rather than using Nuxt's `vite:extend`, `vite:extendConfig` and `vite:configResolved`.
+::
+
+::read-more{to="/docs/4.x/api/kit/builder#addviteplugin"}
+Read more about `addVitePlugin` in the Nuxt Kit documentation.
+::
diff --git a/docs/3.api/5.kit/14.builder.md b/docs/3.api/5.kit/14.builder.md
@@ -14,6 +14,10 @@ Nuxt have builders based on [Vite](https://github.com/nuxt/nuxt/tree/main/packag
 
 Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.
 
+::warning
+This hook is now deprecated, and we recommend using a Vite plugin instead with a `config` hook.
+::
+
 ### Usage
 
 ```ts twoslash
diff --git a/docs/3.api/5.kit/15.examples.md b/docs/3.api/5.kit/15.examples.md
@@ -22,11 +22,9 @@ import { buildNuxt, loadNuxt } from '@nuxt/kit'
 async function getViteConfig () {
   const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
   return new Promise((resolve, reject) => {
-    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
-      if (isClient) {
-        resolve(config)
-        throw new Error('_stop_')
-      }
+    nuxt.hook('vite:extend', (config) => {
+      resolve(config)
+      throw new Error('_stop_')
     })
     buildNuxt(nuxt).catch((err) => {
       if (!err.toString().includes('_stop_')) {
diff --git a/docs/3.api/6.advanced/1.hooks.md b/docs/3.api/6.advanced/1.hooks.md
@@ -75,8 +75,8 @@ Hook                     | Arguments                  | Description
 `schema:beforeWrite`     | `schema`                   | Called before writing the given schema.
 `schema:written`         | -                          | Called after the schema is written.
 `vite:extend`            | `viteBuildContext`         | Allows extending Vite default context.
-`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config.
-`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config.
+`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config. **Deprecated.** We recommend adding a Vite plugin with a `config` hook.
+`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated.** We recommend adding a Vite plugin with a `configResolved` hook.
 `vite:serverCreated`     | `viteServer, env`          | Called when the Vite server is created.
 `vite:compiled`          | -                          | Called after Vite server is compiled.
 `webpack:config`         | `webpackConfigs`           | Called before configuring the webpack compiler.
