@nuxt/docs 4.1.2 → 4.2.0

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

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and the `installModule` function to install a module programmatically.
+Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and specify dependencies using the `moduleDependencies` option.
 
 ## `defineNuxtModule`
 
@@ -22,16 +22,16 @@ import { defineNuxtModule } from '@nuxt/kit'
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
-    configKey: 'myModule'
+    configKey: 'myModule',
   },
   defaults: {
-    enabled: true
+    enabled: true,
   },
   setup (options) {
     if (options.enabled) {
       console.log('My Nuxt module is enabled!')
     }
-  }
+  },
 })
 ```
 
@@ -62,6 +62,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `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.                           |
+| `moduleDependencies` | `Record<string, ModuleDependency> \| ((nuxt: Nuxt) => Record<string, ModuleDependency>)`{lang="ts"} | `false`  | Dependencies on other modules with version constraints and configuration. Can be an object or a function that receives the Nuxt instance. See [example](#specifying-module-dependencies). |
 | `onInstall`        | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                        | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined. |
 | `onUpgrade`        | `(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`{lang="ts"} | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined. |
 | `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.    |
@@ -78,17 +79,17 @@ import { defineNuxtModule } from '@nuxt/kit'
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
-    configKey: 'myModule'
+    configKey: 'myModule',
   },
   defaults: {
     // Module options
-    enabled: true
+    enabled: true,
   },
   setup (options) {
     if (options.enabled) {
       console.log('My Nuxt module is enabled!')
     }
-  }
+  },
 })
 ```
 
@@ -97,8 +98,8 @@ Users can provide options for this module under the corresponding key in `nuxt.c
 ```ts
 export default defineNuxtConfig({
   myModule: {
-    enabled: false
-  }
+    enabled: false,
+  },
 })
 ```
 
@@ -116,7 +117,7 @@ export default defineNuxtModule({
       nuxt: '>=3.0.0', // or use '^3.0.0'
     },
   },
-  async setup() {
+  setup () {
     const resolver = createResolver(import.meta.url)
     // Implement
   },
@@ -148,26 +149,26 @@ interface ModuleOptions {
 export default defineNuxtModule<ModuleOptions>().with({
   meta: {
     name: '@nuxtjs/my-api',
-    configKey: 'myApi'
+    configKey: 'myApi',
   },
   defaults: {
     baseURL: 'https://api.example.com',
     timeout: 5000,
-    retries: 3
+    retries: 3,
   },
-  setup(resolvedOptions, nuxt) {
+  setup (resolvedOptions, nuxt) {
     // resolvedOptions is properly typed as:
     // {
     //   apiKey: string          // Required, no default provided
     //   baseURL: string         // Required, has default value
     //   timeout: number         // Optional, has default value
-    //   retries: number         // Optional, has default value  
+    //   retries: number         // Optional, has default value
     // }
-    
+
     console.log(resolvedOptions.baseURL) // ✅ TypeScript knows this is always defined
     console.log(resolvedOptions.timeout) // ✅ TypeScript knows this is always defined
     console.log(resolvedOptions.retries) // ✅ TypeScript knows this is always defined
-  }
+  },
 })
 ```
 
@@ -197,50 +198,135 @@ export default defineNuxtModule({
   meta: {
     name: 'my-awesome-module',
     version: '1.2.0', // Required for lifecycle hooks
-    configKey: 'myAwesomeModule'
+    configKey: 'myAwesomeModule',
   },
   defaults: {
     apiKey: '',
-    enabled: true
+    enabled: true,
   },
-  
-  onInstall(nuxt) {
+
+  onInstall (nuxt) {
     // This runs only when the module is first installed
     console.log('Setting up my-awesome-module for the first time!')
-    
+
     // You might want to:
     // - Create initial configuration files
     // - Set up database schemas
     // - Display welcome messages
     // - Perform initial data migration
   },
-  
-  onUpgrade(options, nuxt, previousVersion) {
+
+  onUpgrade (options, nuxt, previousVersion) {
     // This runs when the module is upgraded to a newer version
     console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)
-    
+
     // You might want to:
     // - Migrate configuration files
-    // - Update database schemas  
+    // - Update database schemas
     // - Clean up deprecated files
     // - Display upgrade notes
-    
+
     if (semver.lt(previousVersion, '1.1.0')) {
       console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
     }
   },
-  
-  setup(options, nuxt) {
+
+  setup (options, nuxt) {
     // Regular setup logic runs on every build
     if (options.enabled) {
       // Configure the module
     }
-  }
+  },
+})
+```
+
+#### Specifying Module Dependencies
+
+You can use the `moduleDependencies` option to declare dependencies on other modules. This provides a robust way to ensure proper setup order, version compatibility, and configuration management.
+
+The `moduleDependencies` option can be either an object or a function that receives the Nuxt instance:
+
+##### Example
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // Specify a version constraint (semver format)
+      version: '>=6.0.0',
+      // Configuration that overrides user settings
+      overrides: {
+        exposeConfig: true,
+      },
+      // Configuration that sets defaults but respects user settings
+      defaults: {
+        config: {
+          darkMode: 'class',
+        },
+      },
+    },
+    '@nuxtjs/fontaine': {
+      // Optional dependencies won't be installed but ensure that options
+      // can be set if they _are_ installed
+      optional: true,
+      defaults: {
+        fonts: [
+          {
+            family: 'Roboto',
+            fallbacks: ['Impact'],
+          },
+        ],
+      },
+    },
+  },
+  setup (options, nuxt) {
+
+  },
+})
+```
+
+You can also use a function to dynamically determine dependencies based on the Nuxt configuration:
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies (nuxt) {
+    const dependencies: Record<string, any> = {
+      '@nuxtjs/tailwindcss': {
+        version: '>=6.0.0',
+      },
+    }
+
+    // Conditionally add dependencies based on Nuxt config
+    if (nuxt.options.experimental?.someFeature) {
+      dependencies['@nuxtjs/fontaine'] = {
+        optional: true,
+      }
+    }
+
+    return dependencies
+  },
+  setup (options, nuxt) {
+    // Your setup logic runs after all dependencies are initialized
+  },
 })
 ```
 
 ## `installModule`
 
+::callout{type="warning"}
+**Deprecated:** Use the [`moduleDependencies`](#specifying-module-dependencies) option in `defineNuxtModule` instead. The `installModule` function will be removed (or may become non-blocking) in a future version.
+::
+
 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.
 
 ### Usage
@@ -248,7 +334,7 @@ Install specified Nuxt module programmatically. This is helpful when your module
 ```ts twoslash
 import { defineNuxtModule, installModule } from '@nuxt/kit'
 
-export default defineNuxtModule({  
+export default defineNuxtModule({
   async setup () {
     // will install @nuxtjs/fontaine with Roboto font and Impact fallback
     await installModule('@nuxtjs/fontaine', {
@@ -258,10 +344,10 @@ export default defineNuxtModule({
           family: 'Roboto',
           fallbacks: ['Impact'],
           fallbackName: 'fallback-a',
-        }
-      ]
+        },
+      ],
     })
-  }
+  },
 })
 ```
 
@@ -284,7 +370,7 @@ async function installModule (moduleToInstall: string | NuxtModule, inlineOption
 ```ts
 import { defineNuxtModule, installModule } from '@nuxt/kit'
 
-export default defineNuxtModule({  
+export default defineNuxtModule({
   async setup (options, nuxt) {
     // will install @nuxtjs/fontaine with Roboto font and Impact fallback
     await installModule('@nuxtjs/fontaine', {
@@ -294,9 +380,9 @@ export default defineNuxtModule({
           family: 'Roboto',
           fallbacks: ['Impact'],
           fallbackName: 'fallback-a',
-        }
-      ]
+        },
+      ],
     })
-  }
+  },
 })
 ```

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

@@ -10,7 +10,7 @@ links:
 
 ## `useRuntimeConfig`
 
-At build-time, it is possible to access the resolved Nuxt [runtime config](/docs/guide/going-further/runtime-config).
+At build-time, it is possible to access the resolved Nuxt [runtime config](/docs/4.x/guide/going-further/runtime-config).
 
 ### Type
 

package/3.api/5.kit/10.templates.md

@@ -21,17 +21,17 @@ import { addTemplate, defineNuxtModule } from '@nuxt/kit'
 import { defu } from 'defu'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const globalMeta = defu(nuxt.options.app.head, {
       charset: options.charset,
-      viewport: options.viewport
+      viewport: options.viewport,
     })
 
     addTemplate({
       filename: 'meta.config.mjs',
-      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' })
+      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
     })
-  }
+  },
 })
 ```
 
@@ -88,7 +88,7 @@ In the module above, we generate a virtual file named `meta.config.mjs`. In the
 import { createHead as createServerHead } from '@unhead/vue/server'
 import { createHead as createClientHead } from '@unhead/vue/client'
 import { defineNuxtPlugin } from '#imports'
-// @ts-ignore
+// @ts-expect-error - virtual file
 import metaConfig from '#build/meta.config.mjs'
 
 export default defineNuxtPlugin((nuxtApp) => {
@@ -279,7 +279,9 @@ export default defineNuxtModule({
     ]
     // watch and rebuild routes template list when one of the pages changes
     nuxt.hook('builder:watch', async (event, relativePath) => {
-      if (event === 'change') { return }
+      if (event === 'change') {
+        return
+      }
 
       const path = resolve(nuxt.options.srcDir, relativePath)
       if (updateTemplatePaths.some(dir => path.startsWith(dir))) {

package/3.api/5.kit/11.nitro.md

@@ -17,17 +17,17 @@ Adds a Nitro server handler. Use this if you want to create server middleware or
 ### Usage
 
 ```ts twoslash
-import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
 
     addServerHandler({
       route: '/robots.txt',
-      handler: resolve('./runtime/robots.get')
+      handler: resolve('./runtime/robots.get'),
     })
-  }
+  },
 })
 ```
 
@@ -58,24 +58,24 @@ You can use `addServerHandler` to add a server handler from your module.
 ::code-group
 
 ```ts twoslash [module.ts]
-import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
 
     addServerHandler({
       route: '/robots.txt',
-      handler: resolve('./runtime/robots.get')
+      handler: resolve('./runtime/robots.get'),
     })
-  }
+  },
 })
 ```
 
 ```ts twoslash [runtime/robots.get.ts]
 export default defineEventHandler(() => {
   return {
-    body: `User-agent: *\nDisallow: /`
+    body: `User-agent: *\nDisallow: /`,
   }
 })
 ```
@@ -97,19 +97,19 @@ Adds a Nitro server handler to be used only in development mode. This handler wi
 
 ```ts twoslash
 import { defineEventHandler } from 'h3'
-import { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
+import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     addDevServerHandler({
       handler: defineEventHandler(() => {
         return {
-          body: `Response generated at ${new Date().toISOString()}`
+          body: `Response generated at ${new Date().toISOString()}`,
         }
       }),
-      route: '/_handler'
+      route: '/_handler',
     })
-  }
+  },
 })
 ```
 
@@ -139,18 +139,18 @@ In some cases, you may want to create a server handler specifically for developm
 
 ```ts
 import { joinURL } from 'ufo'
-import { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
+import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  async setup(options, nuxt) {
+  async setup (options, nuxt) {
     const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')
 
-    // @ts-ignore
+    // @ts-expect-error - tailwind-config-viewer does not have correct types
     const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
     const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()
 
     addDevServerHandler({ route, handler: viewerDevMiddleware })
-  }
+  },
 })
 ```
 
@@ -172,14 +172,14 @@ Changes to the Nitro instance configuration are not applied.
 import { defineNuxtModule, useNitro } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const resolver = createResolver(import.meta.url)
 
     nuxt.hook('ready', () => {
       const nitro = useNitro()
       // Do something with Nitro instance
     })
-  }
+  },
 })
 ```
 
@@ -197,16 +197,20 @@ Add plugin to extend Nitro's runtime behavior.
 You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).
 ::
 
+::warning
+It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
+::
+
 ### Usage
 
 ```ts twoslash
-import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
+import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     const { resolve } = createResolver(import.meta.url)
     addServerPlugin(resolve('./runtime/plugin.ts'))
-  }
+  },
 })
 ```
 
@@ -227,30 +231,30 @@ function addServerPlugin (plugin: string): void
 ::code-group
 
 ```ts [module.ts]
-import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
+import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     const { resolve } = createResolver(import.meta.url)
     addServerPlugin(resolve('./runtime/plugin.ts'))
-  }
+  },
 })
 ```
 
 ```ts [runtime/plugin.ts]
 export default defineNitroPlugin((nitroApp) => {
-  nitroApp.hooks.hook("request", (event) => {
-    console.log("on request", event.path);
-  });
-
-  nitroApp.hooks.hook("beforeResponse", (event, { body }) => {
-    console.log("on response", event.path, { body });
-  });
-
-  nitroApp.hooks.hook("afterResponse", (event, { body }) => {
-    console.log("on after response", event.path, { body });
-  });
-});
+  nitroApp.hooks.hook('request', (event) => {
+    console.log('on request', event.path)
+  })
+
+  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
+    console.log('on response', event.path, { body })
+  })
+
+  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
+    console.log('on after response', event.path, { body })
+  })
+})
 ```
 
 ::
@@ -262,7 +266,7 @@ Add routes to be prerendered to Nitro.
 ### Usage
 
 ```ts
-import { defineNuxtModule, addPrerenderRoutes } from '@nuxt/kit'
+import { addPrerenderRoutes, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
@@ -273,11 +277,11 @@ export default defineNuxtModule({
     sitemapUrl: '/sitemap.xml',
     prerender: true,
   },
-  setup(options) {
+  setup (options) {
     if (options.prerender) {
       addPrerenderRoutes(options.sitemapUrl)
     }
-  }
+  },
 })
 ```
 
@@ -300,22 +304,22 @@ Add imports to the server. It makes your imports available in Nitro without the
 ### Usage
 
 ```ts twoslash
-import { defineNuxtModule, createResolver, addServerImports } from '@nuxt/kit'
+import { addServerImports, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options) {
+  setup (options) {
     const names = [
       'useStoryblok',
       'useStoryblokApi',
       'useStoryblokBridge',
       'renderRichText',
-      'RichTextSchema'
+      'RichTextSchema',
     ]
 
-    names.forEach((name) =>
-      addServerImports({ name, as: name, from: '@storyblok/vue' })
+    names.forEach(name =>
+      addServerImports({ name, as: name, from: '@storyblok/vue' }),
     )
-  }
+  },
 })
 ```
 
@@ -347,17 +351,17 @@ Add a directory to be scanned for auto-imports by Nitro.
 ### Usage
 
 ```ts twoslash
-import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'
+import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
     configKey: 'myModule',
   },
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
     addServerImportsDir(resolve('./runtime/server/composables'))
-  }
+  },
 })
 ```
 
@@ -381,22 +385,22 @@ You can use `addServerImportsDir` to add a directory to be scanned by Nitro. Thi
 ::code-group
 
 ```ts twoslash [module.ts]
-import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'
+import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
     configKey: 'myModule',
   },
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
     addServerImportsDir(resolve('./runtime/server/composables'))
-  }
+  },
 })
 ```
 
 ```ts twoslash [runtime/server/composables/index.ts]
-export function useApiSecret() {
+export function useApiSecret () {
   const { apiSecret } = useRuntimeConfig()
   return apiSecret
 }
@@ -427,17 +431,17 @@ Only `~/server/api`, `~/server/routes`, `~/server/middleware`, and `~/server/uti
 ### Usage
 
 ```ts twoslash
-import { defineNuxtModule, createResolver, addServerScanDir } from '@nuxt/kit'
+import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
     configKey: 'myModule',
   },
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
     addServerScanDir(resolve('./runtime/server'))
-  }
+  },
 })
 ```
 
@@ -461,22 +465,22 @@ You can use `addServerScanDir` to add a directory to be scanned by Nitro. This i
 ::code-group
 
 ```ts twoslash [module.ts]
-import { defineNuxtModule, createResolver, addServerScanDir } from '@nuxt/kit'
+import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
     configKey: 'myModule',
   },
-  setup(options) {
+  setup (options) {
     const { resolve } = createResolver(import.meta.url)
     addServerScanDir(resolve('./runtime/server'))
-  }
+  },
 })
 ```
 
 ```ts twoslash [runtime/server/utils/index.ts]
-export function hello() {
+export function hello () {
   return 'Hello from server utils!'
 }
 ```
@@ -485,7 +489,7 @@ export function hello() {
 You can then use the `hello` function in your server code.
 
 ```ts twoslash [runtime/server/api/hello.ts]
-function hello() {
+function hello () {
   return 'Hello from server utils!'
 }
 // ---cut---