A toolkit module is rarely alone: it pulls in an icon set, a colour-mode module, maybe i18n, and it has to do that without stealing control from the consumer. Nuxt used to offer one tool for this — installModule — and it had no notion of ordering, version constraints or "the user already configured that". Nuxt 4.1 replaced it with a declarative field, and the comparison between the two is a favourite interview question because the answer is really about who owns the consumer's config.

Know

• installModule(name, options?, nuxt?) runs another module's setup imperatively and immediately, inline in yours. It has no version constraints and no ordering logic. The kit reference now marks it deprecated in favour of moduleDependencies, and says it "will be removed (or may become non-blocking) in a future version" — so it is deprecated, not removed: it is still exported and still works on Nuxt 4. It still has one honest use: installing something conditionally at a point where you already know the decision and no constraint is needed.
• moduleDependencies (Nuxt ≥ 4.1) is a field on the defineNuxtModule definition, alongside meta, defaults, schema, hooks, setup, onInstall and onUpgrade — that is the complete documented field list. Each entry takes exactly four keys, version, defaults, overrides and optional:

  moduleDependencies: {
    '@nuxt/icon': { version: '>=1', defaults: { size: '1em' }, overrides: { mode: 'svg' }, optional: false },
  }
  

  
  Nuxt resolves these before your setup runs: it checks the version constraint, orders the dependency ahead of you, and merges options so that defaults sit under the user's config and overrides sit over it. Nuxt UI uses the same mechanism to pull in @nuxt/icon, @nuxt/fonts and @nuxtjs/color-mode.
• The merge direction is the whole point. defaults are your preference and the consumer can change them; overrides are a requirement of your integration and the consumer cannot. Putting something in overrides is a promise you will support forever, so use it only where a different value would actually break you.
• optional: true means "configure it if it is there, do not install it if it is not". That is what you want for an integration the toolkit enhances rather than requires.
• hasNuxtModule(name) answers "is this module present?" by checking _installedModules and the modules array, so it also sees modules declared after yours — unlike reading nuxt.options, which only reflects modules that already ran. hasNuxtModuleCompatibility(module, semver) adds a version check, with getNuxtModuleVersion underneath.
• Dependency strategy in package.json:
  • @nuxt/kit — a normal dependency, pinned to the Nuxt major you support (^4.0.0). Your module imports it at build time; the consumer should not have to install it.
  • nuxt and vue — devDependencies plus peerDependencies. You build and test against them; the app owns the installed copy. Never a plain dependency, or a consumer ends up with two Vue instances.
  • Heavy runtime libraries — dependencies, because src/runtime is transpiled rather than bundled and its imports stay live. Move one to a peerDependency (documented, with peerDependenciesMeta.optional where appropriate) only when the host app genuinely should control the version, for example a charting or i18n library the app also uses directly.
• Cooperate through hooks, not imports. Consume other modules' hooks (i18n:registerModule, tailwindcss:config, components:extend) and expose your own (see Hooks). Importing another module's internals couples you to its file layout; a hook is a contract it maintains.
• Layers change the ordering question. A team layer lists nuxt-team-toolkit in modules, and the consuming project may list it too. Nuxt deduplicates by meta.name, so it runs once — but the position comes from the merged array, which is why anything order-sensitive belongs in moduleDependencies or modules:done rather than in an assumption about where consumers put you.

How it works

Declarative dependencies, with a conditional integration alongside them:

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

export interface ModuleOptions { theme: 'default' | 'compact' }

const { resolve } = createResolver(import.meta.url)

export default defineNuxtModule<ModuleOptions>().with({
  meta: { name: 'nuxt-team-toolkit', configKey: 'toolkit', version: '1.4.0', compatibility: { nuxt: '>=4.0.0' } },
  defaults: { theme: 'default' },
  moduleDependencies: {
    // required: version-checked, ordered before us, merged around the user's config
    '@nuxt/icon': {
      version: '>=1',
      defaults: { size: '1em' },      // user config wins over these
      overrides: { mode: 'svg' },     // we win over user config — a hard requirement
      optional: false,
    },
    // optional: configured if present, never installed on the user's behalf
    '@nuxtjs/color-mode': { version: '>=3', defaults: { classSuffix: '' }, optional: true },
  },
  async setup (_options, nuxt) {
    const logger = useLogger('nuxt-team-toolkit')

    // sees modules listed *after* us too, unlike reading nuxt.options
    if (hasNuxtModule('@nuxtjs/i18n')) {
      if (!await hasNuxtModuleCompatibility('@nuxtjs/i18n', '>=9')) {
        logger.warn('Toolkit translations need @nuxtjs/i18n >= 9; skipping registration.')
      }
      else {
        nuxt.hook('i18n:registerModule', register => register({
          langDir: resolve('./runtime/lang'),
          locales: [{ code: 'en', file: 'en.json' }],
        }))
      }
    }
  },
})

The imperative form, and why it reads worse:

import { installModule } from '@nuxt/kit'

// runs @nuxt/icon's setup right here, right now:
//  - no version constraint, so an incompatible major fails deep inside someone else's code
//  - runs *before* the consumer's own modules regardless of what they intended
//  - your options are the only ones; there is no defaults/overrides distinction
await installModule('@nuxt/icon', { mode: 'svg' })

What the package.json says about all of it:

{
  "dependencies": {
    "@nuxt/kit": "^4.0.0",
    "defu": "^6.1.4"
  },
  "devDependencies": {
    "@nuxt/module-builder": "^1.0.0",
    "@nuxt/test-utils": "^3.19.0",
    "nuxt": "^4.5.0",
    "vue": "^3.5.0"
  },
  "peerDependencies": {
    "nuxt": "^4.0.0"
  }
}

Exercise

Be able to say