A layer is only useful if consumers can bend it. The override model in Nuxt is deliberately dumb: the same resolved name at a higher priority wins. There is no override: keyword, no registry, no merge of two components. That simplicity is what makes it predictable, and it also produces the sharp edges this page catalogues: what "same name" means for each file type, what cannot be overridden by placing a file, and how to extend instead of replace.

Know

• Components are matched by their resolved component name (path-prefixed by default). A project app/components/Team/Button.vue replaces the layer's app/components/Team/Button.vue because both resolve to TeamButton. A project file with a different path but the same final name also wins, with a warning about the duplicate.
• Pages are matched by route. A project app/pages/settings.vue replaces the layer's settings route; pages the project does not redefine stay. To remove an inherited page use the pages:extend hook and filter the routes.
• Layouts are matched by name (default.vue). Middleware by file name for named middleware; global middleware (*.global.ts) from every layer runs.
• Composables and utils are auto-imports matched by exported name. Same file path → override. Different files exporting the same name → the higher-priority layer wins the import and Nuxt logs a duplicate-import warning; do not rely on it, rename or prefix.
• Plugins with the same relative path are overridden; otherwise plugins from all layers run. Ordering is by file name across the merged list, so a layer's 01.team-setup.ts runs before the project's 02.tracking.ts; use dependsOn in the object syntax when order matters rather than trusting names.
• Server handlers in server/api and server/routes are matched by path; server/middleware from every layer runs on every request. Namespace layer routes (/api/_team/...) so an app cannot collide by accident.
• app.vue, error.vue, app/router.options.ts come from the project if present, otherwise from the highest-priority layer that has one. A layer app.vue is a legitimate way to ship a default shell with <NuxtLayout> and <NuxtPage>.
• Wrap instead of replace with the #layers/<name> alias: the project component imports the layer's original by path and renders it inside, adding props, classes or slots. This keeps the layer's future fixes flowing into the app.

How it works

Three ways to change a layer component, in order of preference:

// 1. Configure: the layer exposes knobs in app.config; the project sets them. No override at all.
export default defineAppConfig({
  team: { button: { rounded: 'full', size: 'lg' } },
})

<script setup lang="ts">
// 2. Wrap: replace the registration but keep rendering the original.
import LayerButton from '#layers/base/app/components/Team/Button.vue'
</script>

<template>
  <LayerButton v-bind="$attrs" data-analytics="cta">
    <slot />
  </LayerButton>
</template>

<!-- 3. Replace: same path, brand-new implementation. The layer's version is no longer registered. -->
<template>
  <button class="btn"><slot /></button>
</template>

Removing an inherited route, which no file placement can do:

export default defineNuxtConfig({
  hooks: {
    'pages:extend'(pages) {
      const drop = new Set(['/legacy-dashboard'])
      for (let i = pages.length - 1; i >= 0; i--) {
        if (drop.has(pages[i]!.path)) pages.splice(i, 1)
      }
    },
  },
})

Proving which file won, from a local module, without guessing:

import { defineNuxtModule } from 'nuxt/kit'

export default defineNuxtModule({
  setup(_options, nuxt) {
    nuxt.hook('components:extend', (components) => {
      const hit = components.find(c => c.pascalName === 'TeamButton')
      console.log('TeamButton resolves to', hit?.filePath)
    })
  },
})

Exercise

Be able to say