@nuxt/docs-nightly 4.2.0-29345108.b399de2f → 4.2.0-29345484.1f69d1e1

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

@@ -501,35 +501,51 @@ export default defineNuxtModule({
 
 #### Using Other Modules in Your Module
 
-If your module depends on other modules, you can add them by using Nuxt Kit's `installModule` utility. For example, if you wanted to use Nuxt Tailwind in your module, you could add it as below:
+If your module depends on other modules, you can specify them using the `moduleDependencies` option. This provides a more robust way to handle module dependencies with version constraints and configuration merging:
 
 ```ts
-import { createResolver, defineNuxtModule, installModule } from '@nuxt/kit'
-
-export default defineNuxtModule<ModuleOptions>({
-  async setup (options, nuxt) {
-    const resolver = createResolver(import.meta.url)
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
 
-    // We can inject our CSS file which includes Tailwind's directives
-    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
+const resolver = createResolver(import.meta.url)
 
-    await installModule('@nuxtjs/tailwindcss', {
-      // module configuration
-      exposeConfig: true,
-      config: {
-        darkMode: 'class',
-        content: {
-          files: [
-            resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
-            resolver.resolve('./runtime/*.{mjs,js,ts}'),
-          ],
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // You can specify a version constraint for the module
+      version: '>=6',
+      // Any configuration that should override `nuxt.options`
+      overrides: {
+        exposeConfig: true,
+      },
+      // Any configuration that should be set. It will override module defaults but
+      // will not override any configuration set in `nuxt.options`
+      defaults: {
+        config: {
+          darkMode: 'class',
+          content: {
+            files: [
+              resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
+              resolver.resolve('./runtime/*.{mjs,js,ts}'),
+            ],
+          },
         },
       },
-    })
+    },
+  },
+  setup (options, nuxt) {
+    // We can inject our CSS file which includes Tailwind's directives
+    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
   },
 })
 ```
 
+::callout{type="info"}
+The `moduleDependencies` option replaces the deprecated `installModule` function and ensures proper setup order and configuration merging.
+::
+
 #### Using Hooks
 
 [Lifecycle hooks](/docs/4.x/guide/going-further/hooks) allow you to expand almost every aspect of Nuxt. Modules can hook to them programmatically or through the `hooks` map in their definition.

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`
 
@@ -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.    |
@@ -239,8 +240,93 @@ export default defineNuxtModule({
 })
 ```
 
+#### 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.2.0-29345108.b399de2f",
+  "version": "4.2.0-29345484.1f69d1e1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",