As camadas Nuxt são um recurso poderoso que você pode usar para compartilhar e reutilizar aplicações Nuxt parciais dentro de um monorepo, ou a partir de um repositório git ou pacote npm. A estrutura das camadas é quase idêntica a uma aplicação Nuxt padrão, o que as torna fáceis de criar e manter.

Um diretório de camada Nuxt mínimo deve conter um arquivo nuxt.config.ts para indicar que é uma camada.

export default defineNuxtConfig({})

Além disso, certos outros arquivos no diretório da camada serão automaticamente escaneados e usados pelo Nuxt para o projeto que estende essa camada.

• components/* - Estende os componentes padrão
• composables/* - Estende os composables padrão
• layouts/* - Estende os layouts padrão
• pages/* - Estende as páginas padrão
• plugins/* - Estende os plugins padrão
• server/* - Estende os endpoints e middleware padrão do servidor
• utils/* - Estende os utils padrão
• nuxt.config.ts- Estende a configuração padrão do nuxt
• app.config.ts - Estende a configuração padrão do app

Exemplo Básico

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

Template Inicial

Para começar, você pode inicializar uma camada com o template nuxt/starter/layer. Isso criará uma estrutura básica sobre a qual você pode construir. Execute este comando no terminal para começar:

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

Siga as instruções do README para os próximos passos.

Publicando Camadas

Você pode publicar e compartilhar camadas usando uma fonte remota ou um pacote npm.

Repositório Git

Você pode usar um repositório git para compartilhar sua camada Nuxt. Alguns exemplos:

export default defineNuxtConfig({
  extends: [
    'github:username/repoName',        // Fonte Remota do GitHub
    'github:username/repoName/base',   // Fonte Remota do GitHub dentro do diretório /base
    'github:username/repoName#dev',    // Fonte Remota do GitHub da branch dev
    'github:username/repoName#v1.0.0', // Fonte Remota do GitHub da tag v1.0.0
    'gitlab:username/repoName',        // Exemplo de Fonte Remota do GitLab
    'bitbucket:username/repoName',     // Exemplo de Fonte Remota do Bitbucket
  ]
})

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

Pacote npm

Você pode publicar camadas Nuxt como um pacote npm que contém os arquivos e dependências que deseja estender. Isso permite que você compartilhe sua configuração com outros, use-a em vários projetos ou use-a de forma privada.

Para estender de um pacote npm, você precisa garantir que o módulo seja publicado no npm e instalado no projeto do usuário como uma devDependency. Então você pode usar o nome do módulo para estender a configuração atual do nuxt:

export default defineNuxtConfig({
  extends: [
    // Módulo Node com escopo
    '@scope/moduleName',
    // ou apenas o nome do módulo
    'moduleName'
  ]
})

Para publicar um diretório de camada como um pacote npm, você deve garantir que o package.json tenha as propriedades corretas preenchidas. Isso garantirá que os arquivos sejam incluídos quando o pacote for publicado.

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

Agora você pode proceder para publicar o módulo no npm, seja publicamente ou de forma privada.

Dicas

Aliases de Camada Nomeados

Camadas escaneadas automaticamente (do seu diretório ~~/layers) criam aliases automaticamente. Por exemplo, você pode acessar sua camada ~~/layers/test via #layers/test.

Se você quiser criar aliases de camada nomeados para outras camadas, pode especificar um nome na configuração da camada.

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

Isso produzirá um alias de #layers/example que aponta para sua camada.

Caminhos Relativos e Aliases

Ao importar usando aliases globais (como ~/ e @/) em componentes e composables de uma camada, note que esses aliases são resolvidos em relação aos caminhos do projeto do usuário. Como solução alternativa, você pode usar caminhos relativos para importá-los, ou usar aliases de camada nomeados.

Além disso, ao usar caminhos relativos no arquivo nuxt.config de uma camada, (com exceção de extends aninhados) eles são resolvidos em relação ao projeto do usuário em vez da camada. Como solução alternativa, use caminhos totalmente resolvidos no 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')
  ]
})

Suporte a Multi-Camadas para Módulos Nuxt

Você pode usar o array interno nuxt.options._layers para suportar o manuseio de multi-camadas personalizadas para seus módulos.

export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // Você pode verificar a existência de um diretório personalizado para estender para cada camada
      console.log('Extensão personalizada para', layer.cwd, layer.config)
    }
  }
})

Notas:

• Itens anteriores no array _layers têm maior prioridade e substituem os posteriores
• O projeto do usuário é o primeiro item no array _layers

Aprofundando

O carregamento de configuração e suporte a extends é gerenciado por unjs/c12, mesclado usando unjs/defu e fontes git remotas são suportadas usando unjs/giget. Confira a documentação e o código-fonte para saber mais.