Most "the layer works in its playground but not in my app" reports come down to one sentence from the docs: global aliases such as ~/ and @/ "are resolved relative to the user's project paths". A layer is merged into somebody else's project, so every path it writes must be anchored to itself. This page is the habit that prevents the whole class of bugs.

Know

• ~, @, ~~, @@ point at the consuming project, both in nuxt.config.ts and inside a layer's runtime code. In the layer's own playground they happen to resolve to the right place, which is why the bug only appears at the first consumer.
• In nuxt.config.ts, anchor to the file:
  layers/base/nuxt.config.ts

  import { dirname, join } from 'node:path'
  import { fileURLToPath } from 'node:url'
  
  const currentDir = dirname(fileURLToPath(import.meta.url))
  
  export default defineNuxtConfig({
    css: [join(currentDir, './app/assets/css/main.css')],
    nitro: { storage: { cache: { driver: 'fs', base: join(currentDir, '.cache') } } },
  })
  

  
  This exact pattern is what layers/base/nuxt.config.ts in this repository does.
• In runtime code, prefer relative imports or auto-imports. A layer component importing ~/composables/useTeamAuth looks for it in the project. Use .//../ paths, rely on auto-imports (the layer's app/composables is scanned anyway), or use the named alias.
• #layers/<name> is the by-path escape hatch. Auto-scanned layers are named after their folder; other layers need $meta: { name }. import { formatDuration } from '#layers/base/app/utils/format' resolves regardless of where the consuming project lives, and it is how a project can wrap a layer component it overrides instead of copying it.
• Only the project's .env is loaded. c12 reads .env from the project root during nuxt dev/build; a .env inside a layer is ignored, and no .env is read by the built server at all. Layer runtimeConfig defaults must therefore be non-secret literal values, with each app supplying NUXT_* variables in its own environment.
• Tailwind v4 scans from the project. Automatic source detection starts at the project root and skips node_modules, so classes used inside a layer under layers/ are found, while a layer consumed from npm is invisible until the CSS entry says @source "../../../node_modules/@team/nuxt-layer-base"; (three levels up from app/assets/css/main.css to the project root).
• TypeScript follows the same rule. Nuxt generates .nuxt/tsconfig.*.json with paths for every layer, so layer code type-checks inside any consumer and inside the playground; a layer package's own tsconfig.json should just extends the playground's generated one.

How it works

The wrap-and-override pattern, which needs the alias:

<script setup lang="ts">
// The project overrides the layer's TeamButton by path, but still renders the original inside.
import BaseTeamButton from '#layers/base/app/components/Team/Button.vue'
</script>

<template>
  <BaseTeamButton v-bind="$attrs" class="tracking-wide">
    <slot />
  </BaseTeamButton>
</template>

In a module that ships with the layer, use kit's resolver instead of hand-rolled URL code:

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

export default defineNuxtModule({
  meta: { name: 'team-devtools' },
  setup() {
    const { resolve } = createResolver(import.meta.url)
    addPlugin(resolve('./runtime/plugin.client'))   // anchored to the module file, not the project
  },
})

Exercise

Be able to say