Module Dependencies

Declare dependencies on other modules with version constraints and configuration merging.

If your module depends on other modules, you can declare them using the moduleDependencies option. Nuxt then ensures those modules are installed in the correct order, validates any version constraints you provide, and merges configuration you supply for them.

Basic Usage

import { createResolver, defineNuxtModule } from '@nuxt/kit'

const resolver = createResolver(import.meta.url)

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'))
  },
})
The moduleDependencies option replaces the deprecated installModule function.

The key of each entry identifies the module to depend on. You can use an npm package name, a path to a local module directory, or a Nuxt alias such as ~ or @.

Depending on Local Modules

When the dependency lives inside the modules/ directory, use a file path to declare the dependency:

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  moduleDependencies: {
    // Path relative to the project root
    './modules/my-local-module': {},
    // Or using a Nuxt alias
    '~/modules/another-local-module': {},
  },
  // ...
})
Relative paths are resolved from your project's rootDir, not from the file declaring the dependency. A module at modules/foo.ts referencing modules/bar.ts must use './modules/bar', not './bar'. Using a Nuxt alias such as ~/modules/bar avoids this ambiguity.

Options

Each entry in moduleDependencies accepts the following fields:

  • version: A semver range. If the resolved module's version does not satisfy this range, Nuxt throws an error. Version checks only apply when the dependency can be resolved to a package.json, so they are a no-op for project-local modules.
  • overrides: Configuration applied on top of nuxt.options, taking precedence over user configuration.
  • defaults: Configuration applied below nuxt.options. User configuration takes precedence over these.
  • optional: If true, the module is not installed automatically when missing. overrides and defaults are still applied if the module is installed elsewhere.