@nuxt/docs 3.17.1 → 3.17.2

package/3.api/5.kit/8.layout.md

@@ -18,63 +18,82 @@ Register template as layout and add it to the layouts.
 In Nuxt 2 `error` layout can also be registered using this utility. In Nuxt 3+ `error` layout [replaced](/docs/getting-started/error-handling#rendering-an-error-page) with `error.vue` page in project root.
 ::
 
-### Type
-
-```ts
-function addLayout (layout: NuxtTemplate | string, name: string): void
-
-interface NuxtTemplate {
-  src?: string
-  filename?: string
-  dst?: string
-  options?: Record<string, any>
-  getContents?: (data: Record<string, any>) => string | Promise<string>
-  write?: boolean
-}
-```
-
-### Parameters
-
-#### `layout`
-
-**Type**: `NuxtTemplate | string`
-
-**Required**: `true`
-
-A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
-
-- `src` (optional)
-
-  **Type**: `string`
-
-  Path to the template. If `src` is not provided, `getContents` must be provided instead.
+### Usage
 
-- `filename` (optional)
+```ts twoslash
+import { addLayout, createResolver, defineNuxtModule } from '@nuxt/kit'
 
-  **Type**: `string`
+export default defineNuxtModule({
+  setup () {
+    const { resolve } = createResolver(import.meta.url)
 
-  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
-
-- `dst` (optional)
-
-  **Type**: `string`
-
-  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
-
-- `options` (optional)
+    addLayout({
+      src: resolve('templates/custom-layout.ts'),
+      filename: 'custom-layout.ts',
+    }, 'custom')
+  },
+})
+```
 
-  **Type**: `Options`
+### Type
 
-  Options to pass to the template.
+```ts
+function addLayout(layout: NuxtTemplate | string, name: string): void
+```
 
-- `getContents` (optional)
+### Parameters
 
-  **Type**: `(data: Options) => string | Promise<string>`
+**`layout`**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
+
+| Property      | Type                                             | Required | Description                                                                                                                                                                      |
+| ------------- | ------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`         | `string`                                         | `false`  | Path to the template. If `src` is not provided, `getContents` must be provided instead.                                                                                          |
+| `filename`    | `string`                                         | `false`  | Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.                                   |
+| `dst`         | `string`                                         | `false`  | Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.                                                |
+| `options`     | `Record<string, any>`{lang="ts"}                 | `false`  | Options to pass to the template.                                                                                                                                                 |
+| `getContents` | `(data) => string \| Promise<string>`{lang="ts"} | `false`  | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored. |
+| `write`       | `boolean`                                        | `false`  | If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.                                         |
+
+**`name`**: The name to register the layout under (e.g., `default`, `custom`, etc.).
+
+### Example
+
+This will register a layout named `custom` that wraps pages with a header and footer.
+
+```ts twoslash
+import { addLayout, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    addLayout({
+      write: true,
+      filename: 'my-layout.vue',
+      getContents: () => `<template>
+  <div>
+    <header>My Header</header>
+    <slot />
+    <footer>My Footer</footer>
+  </div>
+</template>`,
+    }, 'custom')
+  },
+})
+```
 
-  A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.
+You can then use this layout in your pages:
 
-- `write` (optional)
+```vue [pages/about.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: 'custom',
+})
+</script>
 
-    **Type**: `boolean`
+<template>
+  <div>About Page</div>
+</template>
+```
 
-    If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
+::warning
+Due to the lack of support for virtual `.vue` files by `@vitejs/plugin-vue`, you can work around this limitation by passing `write: true` to the first argument of `addLayout`.
+::

package/3.api/5.kit/9.plugins.md

@@ -8,95 +8,81 @@ links:
     size: xs
 ---
 
-Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the `plugins` directory. However, if you need to ship a plugin with your module, Nuxt Kit provides the `addPlugin` and `addPluginTemplate` methods. These utils allow you to customize the plugin configuration to better suit your needs.
+Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the `plugins/` directory. However, if you need to ship a plugin with your module, Nuxt Kit provides the `addPlugin` and `addPluginTemplate` methods. These utils allow you to customize the plugin configuration to better suit your needs.
 
 ## `addPlugin`
 
-Registers a Nuxt plugin and to the plugins array.
+Registers a Nuxt plugin and adds it to the plugins array.
 
 ::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugins?friend=nuxt" target="_blank"}
-Watch Vue School video about addPlugin.
+Watch Vue School video about `addPlugin`.
 ::
 
-### Type
+### Usage
 
-```ts
-function addPlugin (plugin: NuxtPlugin | string, options: AddPluginOptions): NuxtPlugin
+```ts twoslash
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
 
-interface NuxtPlugin {
-  src: string
-  mode?: 'all' | 'server' | 'client'
-  order?: number
-}
+export default defineNuxtModule({
+  setup () {
+    const { resolve } = createResolver(import.meta.url)
 
-interface AddPluginOptions { append?: boolean }
+    addPlugin({
+      src: resolve('runtime/plugin.js'),
+      mode: 'client',
+    })
+  },
+})
 ```
 
-### Parameters
-
-#### `plugin`
-
-**Type**: `NuxtPlugin | string`
-
-**Required**: `true`
-
-A plugin object or a string with the path to the plugin. If a string is provided, it will be converted to a plugin object with `src` set to the string value. If a plugin object is provided, it must have the following properties:
-
-- `src` (required)
-
-  **Type**: `string`
-
-  Path to the plugin.
-
-- `mode` (optional)
-
-  **Type**: `'all' | 'server' | 'client'`
-
-  **Default**: `'all'`
+### Type
 
-  If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
+```ts
+function addPlugin(plugin: NuxtPlugin | string, options?: AddPluginOptions): NuxtPlugin
+```
 
-- `order` (optional)
+### Parameters
 
-  **Type**: `number`
+**`plugin`**: A plugin object or a string with the path to the plugin. If a string is provided, it will be converted to a plugin object with `src` set to the string value.
 
-  **Default**: `0`
+If a plugin object is provided, it must have the following properties:
 
-  Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).
+| Property | Type                                       | Required | Description                                                                                                                                                                                                                                                                                                                                                              |
+| -------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src`    | `string`                                   | `true`   | Path to the plugin file.                                                                                                                                                                                                                                                                                                                                                 |
+| `mode`   | `'all' \| 'server' \| 'client'`{lang="ts"} | `false`  | If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side. |
+| `order`  | `number`                                   | `false`  | Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).      |
 
 ::warning
-Don't use `order` unless you know what you're doing. For most plugins, the default `order` of `0` is sufficient. To append a plugin to the end of the plugins array, use the `append` option instead.
+Avoid using `order` unless necessary. Use `append` if you simply need to register plugins after Nuxt defaults.
 ::
 
-#### `options`
-
-**Type**: `AddPluginOptions`
+**`options`**: Optional object with the following properties:
 
-**Default**: `{}`
-
-Options to pass to the plugin. If `append` is set to `true`, the plugin will be appended to the plugins array instead of prepended.
+| Property | Type      | Required | Description                                                                                                         |
+| -------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `append` | `boolean` | `false`  | If `true`, the plugin will be appended to the plugins array. If `false`, it will be prepended. Defaults to `false`. |
 
 ### Examples
 
 ::code-group
 
 ```ts [module.ts]
-import { createResolver, defineNuxtModule, addPlugin } from '@nuxt/kit'
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
-    const resolver = createResolver(import.meta.url)
+  setup () {
+    const { resolve } = createResolver(import.meta.url)
 
     addPlugin({
-      src: resolver.resolve('runtime/plugin.js'),
-      mode: 'client'
+      src: resolve('runtime/plugin.js'),
+      mode: 'client',
     })
-  }
+  },
 })
 ```
 
-```ts [runtime/plugin.js]
-// https://github.com/nuxt/nuxters
+```ts [runtime/plugin.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const colorMode = useColorMode()
 
@@ -115,139 +101,150 @@ export default defineNuxtPlugin((nuxtApp) => {
 Adds a template and registers as a nuxt plugin. This is useful for plugins that need to generate code at build time.
 
 ::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugin-templates?friend=nuxt" target="_blank"}
-Watch Vue School video about addPluginTemplate.
+Watch Vue School video about `addPluginTemplate`.
 ::
 
+### Usage
+
+```ts twoslash
+import { addPluginTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options) {
+    addPluginTemplate({
+      filename: 'module-plugin.mjs',
+      getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
+export default defineNuxtPlugin({
+  name: 'module-plugin',
+  setup (nuxtApp) {
+    ${options.log ? 'console.log("Plugin install")' : ''}
+  }
+})`,
+    })
+  },
+})
+```
+
 ### Type
 
 ```ts
-function addPluginTemplate (pluginOptions: NuxtPluginTemplate, options: AddPluginOptions): NuxtPlugin
-
-interface NuxtPluginTemplate<Options = Record<string, any>> {
-  src?: string,
-  filename?: string,
-  dst?: string,
-  mode?: 'all' | 'server' | 'client',
-  options?: Options,
-  getContents?: (data: Options) => string | Promise<string>,
-  write?: boolean,
-  order?: number
-}
-
-interface AddPluginOptions { append?: boolean }
-
-interface NuxtPlugin {
-  src: string
-  mode?: 'all' | 'server' | 'client'
-  order?: number
-}
+function addPluginTemplate(pluginOptions: NuxtPluginTemplate, options?: AddPluginOptions): NuxtPlugin
 ```
 
 ### Parameters
 
-#### `pluginOptions`
-
-**Type**: `NuxtPluginTemplate`
-
-**Required**: `true`
-
-A plugin template object with the following properties:
-
-- `src` (optional)
+**`pluginOptions`**: A plugin template object with the following properties:
 
-  **Type**: `string`
+| Property      | Type                                                                  | Required | Description                                                                                                                                                                                                                                                                                                                                                              |
+| ------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src`         | `string`                                                              | `false`  | Path to the template. If `src` is not provided, `getContents` must be provided instead.                                                                                                                                                                                                                                                                                  |
+| `filename`    | `string`                                                              | `false`  | Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.                                                                                                                                                                                                                           |
+| `dst`         | `string`                                                              | `false`  | Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.                                                                                                                                                                                                                                        |
+| `mode`        | `'all' \| 'server' \| 'client'`{lang="ts"}                            | `false`  | If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side. |
+| `options`     | `Record<string, any>`{lang="ts"}                                      | `false`  | Options to pass to the template.                                                                                                                                                                                                                                                                                                                                         |
+| `getContents` | `(data: Record<string, any>) => string \| Promise<string>`{lang="ts"} | `false`  | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.                                                                                                                                                                                         |
+| `write`       | `boolean`                                                             | `false`  | If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.                                                                                                                                                                                                                                 |
+| `order`       | `number`                                                              | `false`  | Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).      |
 
-  Path to the template. If `src` is not provided, `getContents` must be provided instead.
-
-- `filename` (optional)
-
-  **Type**: `string`
-
-  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
-
-- `dst` (optional)
-
-  **Type**: `string`
-
-  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
-
-- `mode` (optional)
-
-  **Type**: `'all' | 'server' | 'client'`
-
-  **Default**: `'all'`
-
-  If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
-
-- `options` (optional)
-
-  **Type**: `Options`
+::warning
+Prefer using `getContents` for dynamic plugin generation. Avoid setting `order` unless necessary.
+::
 
-  Options to pass to the template.
+**`options`**: Optional object with the following properties:
 
-- `getContents` (optional)
+| Property | Type      | Required | Description                                                                                                         |
+| -------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `append` | `boolean` | `false`  | If `true`, the plugin will be appended to the plugins array. If `false`, it will be prepended. Defaults to `false`. |
 
-  **Type**: `(data: Options) => string | Promise<string>`
+### Examples
 
-  A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.
+#### Generate a plugin template with different options
 
-- `write` (optional)
+Use `addPluginTemplate` when you need to generate plugin code dynamically at build time. This allows you to generate different plugin contents based on the options passed to it. For example, Nuxt internally uses this function to generate Vue app configurations.
 
-    **Type**: `boolean`
+```ts twoslash [module.ts]
+import { addPluginTemplate, defineNuxtModule } from '@nuxt/kit'
 
-    If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
+export default defineNuxtModule({
+  setup (_, nuxt) {
+    if (nuxt.options.vue.config && Object.values(nuxt.options.vue.config).some(v => v !== null && v !== undefined)) {
+      addPluginTemplate({
+        filename: 'vue-app-config.mjs',
+        write: true,
+        getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
+export default defineNuxtPlugin({
+  name: 'nuxt:vue-app-config',
+  enforce: 'pre',
+  setup (nuxtApp) {
+    ${Object.keys(nuxt.options.vue.config!)
+        .map(k => `nuxtApp.vueApp.config[${JSON.stringify(k)}] = ${JSON.stringify(nuxt.options.vue.config![k as 'idPrefix'])}`)
+        .join('\n')
+    }
+  }
+})`,
+      })
+    }
+  },
+})
+```
 
-- `order` (optional)
+This generates different plugin code depending on the provided configuration.
 
-  **Type**: `number`
+::code-group
 
-  **Default**: `0`
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  vue: {
+    config: {
+      idPrefix: 'nuxt',
+    },
+  },
+})
+```
 
-  Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).
+```ts [#build/vue-app-config.mjs]
+import { defineNuxtPlugin } from '#app/nuxt'
+export default defineNuxtPlugin({
+  name: 'nuxt:vue-app-config',
+  enforce: 'pre',
+  setup (nuxtApp) {
+    nuxtApp.vueApp.config["idPrefix"] = "nuxt"
+  }
+})
+```
 
-::warning
-Don't use `order` unless you know what you're doing. For most plugins, the default `order` of `0` is sufficient. To append a plugin to the end of the plugins array, use the `append` option instead.
 ::
 
-#### `options`
+#### Using an EJS template to generate a plugin
 
-**Type**: `AddPluginOptions`
-
-**Default**: `{}`
-
-Options to pass to the plugin. If `append` is set to `true`, the plugin will be appended to the plugins array instead of prepended.
-
-### Examples
+You can also use an EJS template to generate your plugin. Options can be passed through the `options` property and then used within the EJS template to generate the plugin content.
 
 ::code-group
 
 ```ts [module.ts]
-// https://github.com/vuejs/vuefire
-import { createResolver, defineNuxtModule, addPluginTemplate } from '@nuxt/kit'
+import { addPluginTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
-    const resolver = createResolver(import.meta.url)
+  setup (options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
 
     addPluginTemplate({
-      src: resolve(templatesDir, 'plugin.ejs'),
+      src: resolve('templates/plugin.ejs'),
       filename: 'plugin.mjs',
       options: {
-        ...options,
         ssr: nuxt.options.ssr,
       },
     })
-  }
+  },
 })
 ```
 
-```ts [runtime/plugin.ejs]
+```ts [templates/plugin.ejs]
 import { VueFire, useSSRInitialState } from 'vuefire'
 import { defineNuxtPlugin } from '#imports'
 
 export default defineNuxtPlugin((nuxtApp) => {
   const firebaseApp = nuxtApp.$firebaseApp
-
   nuxtApp.vueApp.use(VueFire, { firebaseApp })
 
   <% if(options.ssr) { %>
@@ -261,3 +258,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 ```
 
 ::
+
+::warning
+If you set `compatibilityVersion` to `4`, Nuxt no longer uses `lodash.template` to compile templates by default. You can still enable it via the `experimental.compileTemplate` option, but support for EJS templates will be removed entirely in the next major version.
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "3.17.1",
+  "version": "3.17.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",