The most valuable thing a base layer does for a team is often not a component but a preset: "every app gets Nuxt UI, ESLint, fonts, icons and image optimisation, configured our way, from one extends line". That works because a layer's nuxt.config can list modules and their options exactly like a project's. This page covers both sides of the relationship: layers that carry modules, and modules that must behave correctly when files are spread across layers. The Module authoring section covers the modules themselves.

Know

• A layer lists modules like an app does. modules: ['@nuxt/ui', '@nuxt/eslint'] in the layer becomes part of the merged array. The layer's package.json must declare those modules as dependencies so consumers install them.
• Deduplication. Nuxt deduplicates modules declared in several layers, so the project and two layers can all list @nuxt/image and its setup runs once. Module options are merged with defu across all layers before that single setup runs.
• Disabling. A project switches an inherited module off by setting its config key to false (image: false, pinia: false). This is documented behaviour, not a trick, and is how you keep a preset opinionated but escapable.
• moduleDependencies (Nuxt ≥ 4.1) lets a module declare that it depends on another module with version constraints, defaults and overrides. In a toolkit, the team module declares its dependencies this way while the layer stays a plain list.
• Local modules/ directories are auto-registered for the project (modules/*.ts, modules/*/index.ts, alphabetical, after nuxt.config modules). A layer can ship the same directory for machinery that belongs with it. Nuxt 5
• Layer-aware modules never assume a single srcDir. They iterate getLayerDirectories() (or nuxt.options._layers) and scan each layer, project first, so that the project's files override a layer's. @nuxt/content does this for components/content, which is why the callout components used on these pages can live in layers/base.
• Everything runs once, in the project's process. A module listed by a layer still executes in the consuming app's build with the merged options; it has no notion of "which layer asked for me" unless it reads _layers.

How it works

The preset side, as this repository does it:

export default defineNuxtConfig({
  $meta: { name: 'base' },
  modules: ['@nuxt/ui'],                 // consumers get Nuxt UI (and its fonts/icons/color-mode) for free
  css: [join(currentDir, './app/assets/css/main.css')],
  icon: { serverBundle: { collections: ['lucide', 'simple-icons'] } },
})

export default defineNuxtConfig({
  modules: ['@nuxt/content', '@vueuse/nuxt', '@nuxt/eslint'],  // merged with the layer's: ui runs once
  // ui: false  <- would switch the inherited module off
})

The module side, scanning every layer with the project winning:

import { existsSync } from 'node:fs'
import { join } from 'node:path'
import { defineNuxtModule, getLayerDirectories, addTemplate } from 'nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'team-locales', configKey: 'teamLocales' },
  setup(_options, nuxt) {
    // getLayerDirectories() is ordered project first, then layers by priority.
    // Reverse it so lower-priority layers register first and higher ones override the same keys.
    const dirs = getLayerDirectories(nuxt).map(l => join(l.root, 'locales')).filter(existsSync).reverse()

    addTemplate({
      filename: 'team-locales.mjs',
      getContents: () => `export const localeDirs = ${JSON.stringify(dirs)}`,
    })
  },
})

Registering a components directory per layer is the same idea:

import { defineNuxtModule, getLayerDirectories, addComponentsDir } from 'nuxt/kit'

export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of [...getLayerDirectories(nuxt)].reverse()) {
      addComponentsDir({ path: `${layer.app}blocks`, prefix: 'Block', pathPrefix: false })
    }
  },
})

Exercise

Be able to say