Las capas de Nuxt son una característica poderosa que puedes usar para compartir y reutilizar aplicaciones parciales de Nuxt dentro de un monorepo, o desde un repositorio git o paquete npm. La estructura de las capas es casi idéntica a una aplicación estándar de Nuxt, lo que las hace fáciles de crear y mantener.

Un directorio mínimo de capa de Nuxt debe contener un archivo nuxt.config.ts para indicar que es una capa.

export default defineNuxtConfig({})

Además, ciertos otros archivos en el directorio de la capa serán escaneados automáticamente y utilizados por Nuxt para el proyecto que extiende esta capa.

• components/* - Extiende los componentes predeterminados
• composables/* - Extiende los composables predeterminados
• layouts/* - Extiende los layouts predeterminados
• pages/* - Extiende las páginas predeterminadas
• plugins/* - Extiende los plugins predeterminados
• server/* - Extiende los endpoints y middleware del servidor predeterminados
• utils/* - Extiende los utils predeterminados
• nuxt.config.ts- Extiende la configuración de nuxt predeterminada
• app.config.ts - Extiende la configuración de la aplicación predeterminada

Ejemplo Básico

export default defineNuxtConfig({
  extends: [
    './base'
  ]
})

Plantilla de Inicio

Para comenzar, puedes inicializar una capa con la plantilla nuxt/starter/layer. Esto creará una estructura básica sobre la que puedes construir. Ejecuta este comando en la terminal para comenzar:

npm create nuxt -- --template layer nuxt-layer

Sigue las instrucciones del README para los siguientes pasos.

Publicación de Capas

Puedes publicar y compartir capas utilizando una fuente remota o un paquete npm.

Repositorio Git

Puedes usar un repositorio git para compartir tu capa de Nuxt. Algunos ejemplos:

export default defineNuxtConfig({
  extends: [
    'github:username/repoName',        // Fuente Remota de GitHub
    'github:username/repoName/base',   // Fuente Remota de GitHub dentro del directorio /base
    'github:username/repoName#dev',    // Fuente Remota de GitHub desde la rama dev
    'github:username/repoName#v1.0.0', // Fuente Remota de GitHub desde la etiqueta v1.0.0
    'gitlab:username/repoName',        // Ejemplo de Fuente Remota de GitLab
    'bitbucket:username/repoName',     // Ejemplo de Fuente Remota de Bitbucket
  ]
})

export default defineNuxtConfig({
  extends: [
    ['github:username/repoName', { install: true }]
  ]
})

Paquete npm

Puedes publicar capas de Nuxt como un paquete npm que contenga los archivos y dependencias que deseas extender. Esto te permite compartir tu configuración con otros, usarla en múltiples proyectos o usarla de manera privada.

Para extender desde un paquete npm, necesitas asegurarte de que el módulo esté publicado en npm e instalado en el proyecto del usuario como una devDependency. Luego puedes usar el nombre del módulo para extender la configuración actual de nuxt:

export default defineNuxtConfig({
  extends: [
    // Módulo de Node con scope
    '@scope/moduleName',
    // o solo el nombre del módulo
    'moduleName'
  ]
})

Para publicar un directorio de capa como un paquete npm, debes asegurarte de que el package.json tenga las propiedades correctas completadas. Esto asegurará que los archivos se incluyan cuando se publique el paquete.

{
  "name": "my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {},
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}

Ahora puedes proceder a publicar el módulo en npm, ya sea públicamente o de manera privada.

Consejos

Alias de Capas Nombradas

Las capas escaneadas automáticamente (desde tu directorio ~~/layers) crean automáticamente alias. Por ejemplo, puedes acceder a tu capa ~~/layers/test a través de #layers/test.

Si deseas crear alias de capas nombradas para otras capas, puedes especificar un nombre en la configuración de la capa.

export default defineNuxtConfig({
  $meta: {
    name: 'example',
  },
})

Esto producirá un alias de #layers/example que apunta a tu capa.

Rutas Relativas y Alias

Al importar usando alias globales (como ~/ y @/) en componentes y composables de una capa, ten en cuenta que estos alias se resuelven en relación con las rutas del proyecto del usuario. Como solución, puedes usar rutas relativas para importarlos, o usar alias de capas nombradas.

También al usar rutas relativas en el archivo nuxt.config de una capa, (con excepción de extends anidados) se resuelven en relación con el proyecto del usuario en lugar de la capa. Como solución, usa rutas completamente resueltas en nuxt.config:

import { fileURLToPath } from 'url'
import { dirname, join } from 'path'

const currentDir = dirname(fileURLToPath(import.meta.url))

export default defineNuxtConfig({
  css: [
    join(currentDir, './assets/main.css')
  ]
})

Soporte Multi-Capa para Módulos de Nuxt

Puedes usar el array interno nuxt.options._layers para soportar el manejo personalizado de múltiples capas para tus módulos.

export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // Puedes verificar la existencia de un directorio personalizado para extender cada capa
      console.log('Extensión personalizada para', layer.cwd, layer.config)
    }
  }
})

Notas:

• Los elementos anteriores en el array _layers tienen mayor prioridad y sobrescriben a los posteriores
• El proyecto del usuario es el primer elemento en el array _layers

Profundizando

La carga de configuración y el soporte de extends son manejados por unjs/c12, fusionados usando unjs/defu y las fuentes git remotas son soportadas usando unjs/giget. Consulta la documentación y el código fuente para aprender más.