v4
Nuxt on GitHub

Layers

Source
Nuxt Kit provides utilities to help you work with layers and their directory structures.

Nuxt layers provide a powerful way to share and extend functionality across projects. When working with layers in modules, you often need to access directory paths from each layer. Nuxt Kit provides the getLayerDirectories utility to access resolved directory paths for all layers in your Nuxt application.

getLayerDirectories

Get the resolved directory paths for all layers in a Nuxt application. This function provides a structured way to access layer directories without directly accessing the private nuxt.options._layers property.

Usage

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

export default defineNuxtModule({
  setup() {
    const layerDirs = getLayerDirectories()
    
    // Access directories from all layers
    for (const [index, layer] of layerDirs.entries()) {
      console.log(`Layer ${index}:`)
      console.log(`  Root: ${layer.root}`)
      console.log(`  App: ${layer.app}`)
      console.log(`  Server: ${layer.server}`)
      console.log(`  Pages: ${layer.appPages}`)
      // ... other directories
    }
  }
})

Type

function getLayerDirectories(nuxt?: Nuxt): LayerDirectories[]

interface LayerDirectories {
  /** Nuxt rootDir (`/` by default) */
  readonly root: string
  /** Nitro source directory (`/server` by default) */
  readonly server: string
  /** Local modules directory (`/modules` by default) */
  readonly modules: string
  /** Shared directory (`/shared` by default) */
  readonly shared: string
  /** Public directory (`/public` by default) */
  readonly public: string
  /** Nuxt srcDir (`/app/` by default) */
  readonly app: string
  /** Layouts directory (`/app/layouts` by default) */
  readonly appLayouts: string
  /** Middleware directory (`/app/middleware` by default) */
  readonly appMiddleware: string
  /** Pages directory (`/app/pages` by default) */
  readonly appPages: string
  /** Plugins directory (`/app/plugins` by default) */
  readonly appPlugins: string
}

Parameters

nuxt (optional): The Nuxt instance to get layers from. If not provided, the function will use the current Nuxt context.

Return Value

The getLayerDirectories function returns an array of LayerDirectories objects, one for each layer in the application.

Layer Priority Ordering: The layers are ordered by priority, where:

  • The first layer is the user/project layer (highest priority)
  • Earlier layers override later layers in the array
  • Base layers appear last in the array (lowest priority)

This ordering matches Nuxt's layer resolution system, where user-defined configurations and files take precedence over those from base layers.

LayerDirectories: An object containing the resolved directory paths for a layer.

PropertyTypeDescription
rootstringThe root directory of the layer (equivalent to rootDir)
serverstringThe server directory for Nitro server-side code
modulesstringThe local modules directory
sharedstringThe shared directory for code used by both client and server
appstringThe source directory of the layer (equivalent to srcDir)
publicstringThe public directory for static assets
appLayoutsstringThe layouts directory for Vue layout components
appMiddlewarestringThe middleware directory for route middleware
appPagesstringThe pages directory for file-based routing
appPluginsstringThe plugins directory for Nuxt plugins

Examples

Processing files from all layers:

import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
import { resolve } from 'pathe'
import { globby } from 'globby'

export default defineNuxtModule({
  async setup() {
    const layerDirs = getLayerDirectories()
    
    // Find all component files across layers
    // Note: layerDirs[0] is the user layer (highest priority)
    // Later layers in the array have lower priority
    const componentFiles = []
    for (const [index, layer] of layerDirs.entries()) {
      const files = await globby('**/*.vue', {
        cwd: resolve(layer.app, 'components'),
        absolute: true
      })
      console.log(`Layer ${index} (${index === 0 ? 'user' : 'base'}):`, files.length, 'components')
      componentFiles.push(...files)
    }
  }
})

Adding templates from multiple layers:

import { defineNuxtModule, getLayerDirectories, addTemplate } from '@nuxt/kit'
import { resolve, basename } from 'pathe'
import { existsSync } from 'fs'

export default defineNuxtModule({
  async setup() {
    const layerDirs = getLayerDirectories()
    
    // Add a config file from each layer that has one
    for (const dirs of layerDirs) {
      const configPath = resolve(dirs.app, 'my-module.config.ts')
      if (existsSync(configPath)) {
        addTemplate({
          filename: `my-module-${basename(dirs.root)}.config.ts`,
          src: configPath
        })
      }
    }
  }
})

Respecting layer priority:

import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
import { resolve } from 'pathe'
import { existsSync, readFileSync } from 'fs'

export default defineNuxtModule({
  setup() {
    const layerDirs = getLayerDirectories()
    
    // Find the first (highest priority) layer that has a specific config file
    // This respects the layer priority system
    let configContent = null
    for (const dirs of layerDirs) {
      const configPath = resolve(dirs.app, 'my-config.json')
      if (existsSync(configPath)) {
        configContent = readFileSync(configPath, 'utf-8')
        console.log(`Using config from layer: ${dirs.root}`)
        break // Use the first (highest priority) config found
      }
    }
    
    // Alternative: Collect configs from all layers, with user layer taking precedence
    const allConfigs = {}
    for (const dirs of layerDirs.reverse()) { // Process from lowest to highest priority
      const configPath = resolve(dirs.app, 'my-config.json')
      if (existsSync(configPath)) {
        const config = JSON.parse(readFileSync(configPath, 'utf-8'))
        Object.assign(allConfigs, config) // Later assignments override earlier ones
      }
    }
  }
})

Checking for layer-specific directories:

import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
import { existsSync } from 'fs'
import { resolve } from 'pathe'

export default defineNuxtModule({
  setup() {
    const layerDirs = getLayerDirectories()
    
    // Find layers that have a specific custom directory
    const layersWithAssets = layerDirs.filter(layer => {
      return existsSync(resolve(layer.app, 'assets'))
    })
    
    console.log(`Found ${layersWithAssets.length} layers with assets directory`)
  }
})
The getLayerDirectories function includes caching via a WeakMap to avoid recomputing directory paths for the same layers repeatedly, improving performance when called multiple times.
Directory paths returned by this function always include a trailing slash for consistency.