@nuxt/docs 3.17.1 → 3.17.2

package/1.getting-started/07.routing.md

@@ -131,7 +131,7 @@ definePageMeta({
 
 Nuxt offers route validation via the `validate` property in [`definePageMeta()`](/docs/api/utils/define-page-meta) in each page you wish to validate.
 
-The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, and another match can't be found, this will cause a 404 error. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, this will cause a 404 error. You can also directly return an object with `statusCode`/`statusMessage` to customize the error returned.
 
 If you have a more complex use case, then you can use anonymous route middleware instead.
 

package/1.getting-started/18.upgrade.md

@@ -76,6 +76,7 @@ export default defineNuxtConfig({
   //   spaLoadingTemplateLocation: 'within',
   //   parseErrorData: false,
   //   pendingWhenIdle: true,
+  //   alwaysRunFetchOnKeyChange: true,
   //   defaults: {
   //     useAsyncData: {
   //       deep: true
@@ -752,6 +753,46 @@ export default defineNuxtConfig({
 })
 ```
 
+### Key Change Behavior in `useAsyncData` and `useFetch`
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+When using reactive keys in `useAsyncData` or `useFetch`, Nuxt automatically refetches data when the key changes. When `immediate: false` is set, `useAsyncData` will only fetch data when the key changes if the data has already been fetched once.
+
+Previously, `useFetch` had slightly different behavior. It would always fetch data when the key changed.
+
+Now, `useFetch` and `useAsyncData` behave consistently - by only fetch data when the key changes if the data has already been fetched once.
+
+#### Reasons for Change
+
+This ensures consistent behavior between `useAsyncData` and `useFetch`, and prevents unexpected fetches. If you have set `immediate: false`, then you must call `refresh` or `execute` or data will never be fetched in `useFetch` or `useAsyncData`.
+
+#### Migration Steps
+
+This change should generally improve the expected behavior, but if you were expecting changing the key or options of a non-immediate `useFetch`, you now will need to trigger it manually the first time.
+
+```diff
+  const id = ref('123')
+  const { data, execute } = await useFetch('/api/test', {
+    query: { id },
+    immediate: false
+  )
++ watch(id, execute, { once: true })
+```
+
+To opt out of this behavior:
+
+```ts
+// Or globally in your Nuxt config
+export default defineNuxtConfig({
+  experimental: {
+    alwaysRunFetchOnKeyChange: true
+  }
+})
+```
+
 ### Shallow Data Reactivity in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Minimal

package/2.guide/1.concepts/1.auto-imports.md

@@ -54,7 +54,7 @@ const double = computed(() => count.value * 2)
 
 When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_.
 
-During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.
+During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in the same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.
 
 That means that (with very few exceptions) you cannot use them outside a Nuxt plugin, Nuxt route middleware or Vue setup function. On top of that, you must use them synchronously - that is, you cannot use `await` before calling a composable, except within `<script setup>` blocks, within the setup function of a component declared with `defineNuxtComponent`, in `defineNuxtPlugin` or in `defineNuxtRouteMiddleware`, where we perform a transform to keep the synchronous context even after the `await`.
 

package/2.guide/3.going-further/1.events.md

@@ -0,0 +1,82 @@
+---
+title: "Events"
+description: "Nuxt provides a powerful event system powered by hookable."
+---
+
+# Events
+
+Using events is a great way to decouple your application and allow for more flexible and modular communication between different parts of your code. Events can have multiple listeners that do not depend on each other. For example, you may wish to send an email to your user each time an order has shipped. Instead of coupling your order processing code to your email code, you can emit an event which a listener can receive and use to dispatch an email.
+
+The Nuxt event system is powered by [unjs/hookable](https://github.com/unjs/hookable), which is the same library that powers the Nuxt hooks system.
+
+## Creating Events and Listeners
+
+You can create your own custom events using the `hook` method:
+
+```ts
+const nuxtApp = useNuxtApp()
+
+nuxtApp.hook('app:user:registered', payload => {
+  console.log('A new user has registered!', payload)
+})
+```
+
+To emit an event and notify any listeners, use `callHook`:
+
+```ts
+const nuxtApp = useNuxtApp()
+
+await nuxtApp.callHook('app:user:registered', {
+  id: 1,
+  name: 'John Doe',
+})
+```
+
+You can also use the payload object to enable two-way communication between the emitter and listeners. Since the payload is passed by reference, a listener can modify it to send data back to the emitter.
+
+```ts
+const nuxtApp = useNuxtApp()
+
+nuxtApp.hook('app:user:registered', payload => {
+  payload.message = 'Welcome to our app!'
+})
+
+const payload = {
+  id: 1,
+  name: 'John Doe',
+}
+
+await nuxtApp.callHook('app:user:registered', {
+  id: 1,
+  name: 'John Doe',
+})
+
+// payload.message will be 'Welcome to our app!'
+```
+
+::tip
+You can inspect all events using the **Nuxt DevTools** Hooks panel.
+::
+
+## Augmenting Types
+
+You can augment the types of hooks provided by Nuxt.
+
+```ts
+import { HookResult } from "@nuxt/schema";
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'your-nuxt-runtime-hook': () => HookResult
+  }
+  interface NuxtHooks {
+    'your-nuxt-hook': () => HookResult
+  }
+}
+
+declare module 'nitropack' {
+  interface NitroRuntimeHooks {
+    'your-nitro-hook': () => void;
+  }
+}
+```

package/2.guide/3.going-further/2.hooks.md

@@ -76,23 +76,4 @@ Learn more about available Nitro lifecycle hooks.
 
 ## Additional Hooks
 
-You can add additional hooks by augmenting the types provided by Nuxt. This can be useful for modules.
-
-```ts
-import { HookResult } from "@nuxt/schema";
-
-declare module '#app' {
-  interface RuntimeNuxtHooks {
-    'your-nuxt-runtime-hook': () => HookResult
-  }
-  interface NuxtHooks {
-    'your-nuxt-hook': () => HookResult
-  }
-}
-
-declare module 'nitropack' {
-  interface NitroRuntimeHooks {
-    'your-nitro-hook': () => void;
-  }
-}
-```
+Learn more about creating custom hooks in the [Events section](/docs/guide/going-further/events).

package/3.api/5.kit/1.modules.md

@@ -14,87 +14,57 @@ Modules are the building blocks of Nuxt. Kit provides a set of utilities to help
 
 Define a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.
 
-### Type
+### Usage
 
-```ts
-function defineNuxtModule<OptionsT extends ModuleOptions> (definition: ModuleDefinition<OptionsT> | NuxtModule<OptionsT>): NuxtModule<OptionsT>
-
-type ModuleOptions = Record<string, any>
-
-interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
-  meta?: ModuleMeta
-  defaults?: T | ((nuxt: Nuxt) => T)
-  schema?: T
-  hooks?: Partial<NuxtHooks>
-  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>
-}
-
-interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
-  (this: void, inlineOptions: T, nuxt: Nuxt): Awaitable<void | false | ModuleSetupReturn>
-  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
-  getMeta?: () => Promise<ModuleMeta>
-}
-
-interface ModuleSetupReturn {
-  timings?: {
-    setup?: number
-    [key: string]: number | undefined
+```ts twoslash
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule'
+  },
+  defaults: {
+    enabled: true
+  },
+  setup (options) {
+    if (options.enabled) {
+      console.log('My Nuxt module is enabled!')
+    }
   }
-}
-
-interface ModuleMeta {
-  name?: string
-  version?: string
-  configKey?: string
-  compatibility?: NuxtCompatibility
-  [key: string]: unknown
-}
+})
 ```
 
-### Parameters
-
-#### `definition`
-
-**Type**: `ModuleDefinition<T> | NuxtModule<T>`
-
-**Required**: `true`
-
-A module definition object or a module function.
-
-- `meta` (optional)
-
-  **Type**: `ModuleMeta`
-
-  Metadata of the module. It defines the module name, version, config key and compatibility.
-
-- `defaults` (optional)
-
-  **Type**: `T | ((nuxt: Nuxt) => T)`
-
-  Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
-
-- `schema` (optional)
-
-  **Type**: `T`
-
-  Schema for the module options. If provided, options will be applied to the schema.
+### Type
 
-- `hooks` (optional)
+```ts twoslash
+// @errors: 2391
+import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
+// ---cut---
+export function defineNuxtModule<TOptions extends ModuleOptions> (
+  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
+): NuxtModule<TOptions, TOptions, false>
+```
 
-  **Type**: `Partial<NuxtHooks>`
+### Parameters
 
-  Hooks to be installed for the module. If provided, the module will install the hooks.
+**definition**: A module definition object or a module function. The module definition object should contain the following properties:
 
-- `setup` (optional)
+| Property           | Type                                                                 | Required | Description                                                                                                     |
+| ------------------ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `meta`             | `ModuleMeta`                                                         | `false`  | Metadata of the module. It defines the module name, version, config key and compatibility.                      |
+| `defaults`         | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument. |
+| `schema`           | `T`                                                                  | `false`  | Schema for the module options. If provided, options will be applied to the schema.                              |
+| `hooks`            | `Partial<NuxtHooks>`{lang="ts"}                                      | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                           |
+| `setup`            | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.    |
 
-  **Type**: `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>`
+### Examples
 
-  Setup function for the module. If provided, the module will call the setup function.
+#### Using `configKey` to Make Your Module Configurable
 
-### Examples
+When defining a Nuxt module, you can set a `configKey` to specify how users should configure the module in their `nuxt.config`.
 
 ```ts
-// https://github.com/nuxt/starter/tree/module
 import { defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
@@ -103,51 +73,94 @@ export default defineNuxtModule({
     configKey: 'myModule'
   },
   defaults: {
-    test: 123
+    // Module options
+    enabled: true
   },
-  setup (options, nuxt) {
-    nuxt.hook('modules:done', () => {
-      console.log('My module is ready with current test option: ', options.test)
-    })    
+  setup (options) {
+    if (options.enabled) {
+      console.log('My Nuxt module is enabled!')
+    }
   }
 })
 ```
 
-## `installModule`
-
-Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.
-
-### Type
+Users can provide options for this module under the corresponding key in `nuxt.config`.
 
 ```ts
-async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
+export default defineNuxtConfig({
+  myModule: {
+    enabled: false
+  }
+})
 ```
 
-### Parameters
+#### Defining Module Compatibility Requirements
+
+If you're developing a Nuxt module and using APIs that are only supported in specific Nuxt versions, it's highly recommended to include `compatibility.nuxt`.
 
-#### `moduleToInstall`
+```ts
+export default defineNuxtModule({
+  meta: {
+    name: '@nuxt/icon',
+    configKey: 'icon',
+    compatibility: {
+      // Required nuxt version in semver format.
+      nuxt: '>=3.0.0', // or use '^3.0.0'
+    },
+  },
+  async setup() {
+    const resolver = createResolver(import.meta.url)
+    // Implement
+  },
+})
+```
 
-**Type**: `string` | `NuxtModule`
+If the user tries to use your module with an incompatible Nuxt version, they will receive a warning in the console.
 
-**Required**: `true`
+```terminal
+ WARN  Module @nuxt/icon is disabled due to incompatibility issues:
+ - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0
+```
 
-The module to install. Can be either a string with the module name or a module object itself.
+## `installModule`
 
-#### `inlineOptions`
+Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.
 
-**Type**: `any`
+### Usage
 
-**Default**: `{}`
+```ts twoslash
+import { defineNuxtModule, installModule } from '@nuxt/kit'
 
-An object with the module options to be passed to the module's `setup` function.
+export default defineNuxtModule({  
+  async setup () {
+    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
+    await installModule('@nuxtjs/fontaine', {
+      // module configuration
+      fonts: [
+        {
+          family: 'Roboto',
+          fallbacks: ['Impact'],
+          fallbackName: 'fallback-a',
+        }
+      ]
+    })
+  }
+})
+```
 
-#### `nuxt`
+### Type
 
-**Type**: `Nuxt`
+```ts
+async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
+```
 
-**Default**: `useNuxt()`
+### Parameters
 
-Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+| Property           | Type                                         | Required | Description                                                                                                     |
+| ------------------ | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `moduleToInstall`  | `string \| NuxtModule`{lang="ts"}            | `true`   | The module to install. Can be either a string with the module name or a module object itself.                   |
+| `inlineOptions`    | `any`                                        | `false`  | An object with the module options to be passed to the module's `setup` function.                                |
+| `nuxt`             | `Nuxt`                                       | `false`  | Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.                     |
 
 ### Examples
 

package/3.api/5.kit/10.runtime-config.md

@@ -22,6 +22,8 @@ function useRuntimeConfig (): Record<string, unknown>
 
 It is also possible to update runtime configuration. This will be merged with the existing runtime configuration, and if Nitro has already been initialized it will trigger an HMR event to reload the Nitro runtime config.
 
+### Type
+
 ```ts
 function updateRuntimeConfig (config: Record<string, unknown>): void | Promise<void>
 ```