Once a layer leaves the repository it was born in, it becomes a dependency, and every question a senior asks about dependencies applies: how is it versioned, how do consumers get updates, how fast is the feedback loop when you change it, and what happens when it breaks. The three distribution channels (workspace, npm registry, git) answer those questions differently, and most teams walk through them in that order.

Know

• Start from the template. npm create nuxt -- --template layer @team/nuxt-layer-base scaffolds the layer plus a .playground/ app that extends it. The playground is your dev server and manual test bench; consumers never install it.
• npm packaging rules. package.json needs "type": "module", "main": "./nuxt.config.ts" (yes, the config file is the entry), every runtime dependency the layer's code or listed modules need in dependencies, and nuxt in devDependencies (or peerDependencies with a range you actually test). The docs are explicit: "make sure any dependency imported in the layer is explicitly added to the dependencies". Ship the source, not a build: layers are not compiled.
• Workspace first. In a pnpm monorepo, apps depend on "@team/nuxt-layer-base": "workspace:*" and extends: ['@team/nuxt-layer-base']. Edits hot-reload in every app, one lockfile pins everything, and publishing later is a pnpm publish away.
• Registry for many repos. A private registry (Verdaccio, GitHub Packages, Artifactory, npm Teams) gives semver ranges, changelogs, Renovate PRs and a clear "which version are you on" answer. extends: ['@team/nuxt-layer-base'] stays identical.
• Git when there is no registry. extends: ['github:team/nuxt-layer-base#v2.3.0'] with GIGET_AUTH in CI and install: true if the layer has dependencies. Tags are your versions; treat them as immutable.
• Dev experience differs. Local paths and workspace links watch and hot-reload; an npm-installed layer changes only when you publish and bump; a git layer is downloaded once and cached. For fast iteration on a published layer, temporarily point extends at a local checkout.
• Breaking changes for a layer are anything that forces consumers to edit code or config: renamed or removed components, composables or pages; changed app.config defaults that alter rendering; removed or renamed runtimeConfig keys; a higher minimum Nuxt; a module removed from the preset. Semver them like a library and write the migration note before the release.

How it works

The monorepo layout most teams converge on:

repo/
├─ pnpm-workspace.yaml
├─ packages/
│  ├─ layers/
│  │  ├─ base/            @team/nuxt-layer-base   (design system + preset)
│  │  └─ auth/            @team/nuxt-layer-auth   (extends base? no: apps compose them)
│  └─ modules/
│     └─ toolkit/         @team/nuxt-toolkit      (build-time machinery)
└─ apps/
   ├─ shop/               extends: ['@team/nuxt-layer-base', '@team/nuxt-layer-auth']
   └─ admin/              extends: ['@team/nuxt-layer-base']

packages:
  - packages/layers/*
  - packages/modules/*
  - apps/*

{
  "name": "@team/nuxt-layer-base",
  "version": "2.3.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "files": ["nuxt.config.ts", "app", "server", "shared", "public"],
  "scripts": {
    "dev": "nuxt dev .playground",
    "build": "nuxt build .playground",
    "test": "vitest run",
    "release": "changelogen --release --push && pnpm publish"
  },
  "dependencies": {
    "@nuxt/ui": "^4.11.0",
    "@nuxt/eslint": "^1.17.0",
    "defu": "^6.1.4"
  },
  "devDependencies": {
    "nuxt": "^4.5.0",
    "vitest": "^5.0.0",
    "@nuxt/test-utils": "^4.3.0"
  },
  "peerDependencies": {
    "nuxt": "^4.3.0"
  }
}

{
  "dependencies": {
    "@team/nuxt-layer-base": "workspace:*",
    "@team/nuxt-layer-auth": "workspace:*",
    "nuxt": "^4.5.0"
  }
}

export default defineNuxtConfig({
  extends: ['@team/nuxt-layer-auth', '@team/nuxt-layer-base'],  // auth may override base
})

The same consumer, when the layer moves to a private registry or to git, changes only the source string:

export default defineNuxtConfig({
  extends: [
    '@team/nuxt-layer-base',                                   // registry: ^2 in package.json
    // ['github:team/nuxt-layer-base#v2.3.0', { install: true }], // git alternative
  ],
})

Exercise

Be able to say