Diretório de Módulos

A Nuxt fornece um sistema de módulo de ordem superior que permite estender o núcleo. Os módulos são funções chamadas sequencialmente ao inicializar a Nuxt.

Explorar os Módulos da Nuxt

É possível descobrir na nossa lista de módulos , códigos para impulsionar o nosso projeto de Nuxt, criados pela equipa e pela comunidade da Nuxt.

• 165+ Módulos
• 105+ Colaboradores (Responsáveis)

Ao programar aplicações de produção com a Nuxt, podemos descobrir que a funcionalidade principal da abstração não é suficiente. A Nuxt pode ser estendida com opções de configuração e extensões, mas a manutenção destas personalizações em vários projetos é tediosa, repetitiva e morosa. Por outro lado, suportar de imediato as necessidades de todos os projetos complicaria e dificultaria o uso da Nuxt.

Esta é uma das razões pelas quais a Nuxt fornece um sistema de módulos de ordem superior que possibilita a extensão do núcleo. Os módulos são funções chamadas sequencialmente ao inicializar a Nuxt. A abstração espera cada módulo terminar antes de continuar. Desta maneira, os módulos podem personalizar quase todos os aspetos do nosso projeto. Graças ao desenho modular da Nuxt (baseado na tapable da Webpack), os módulos podem facilmente registar funções gatilhos para certos pontos de entrada como a inicialização do construtor. O módulos também podem sobrepor os modelos de marcação de hipertexto, configurar os carregadores da Webpack, adicionar bibliotecas de folhas de estilo em cascata, e realizar muitas outras tarefas úteis.

O melhor de tudo é que os módulos da Nuxt podem ser incorporados nos pacotes de npm. Isto permite a reutilização em vários projetos e a partilha com a comunidade, ajudando a criar um ecossistema de complementos (extensões) de alta qualidade.

A Propriedade modules

Os módulos são extensões de Nuxt que podem estender a funcionalidade principal da abstração e adicionar integrações infinitas. Depois de instalarmos os módulos, podemos adicioná-los ao nosso ficheiro nuxt.config.js na propriedade modules:

export default {
  modules: [
    // Usar o nome do pacote.
    '@nuxtjs/axios',

    // Relativo ao diretório de origem do nosso projeto.
    '~/modules/awesome.js',

    // Fornecer opções
    ['@nuxtjs/google-analytics', { ua: 'X1234567' }],

    // Definição em linha
    function () {}
  ]
}

A Nuxt tenta resolver cada elemento do vetor de módulos usando o caminho exigido pelo nó (no node_modules) e então resolverá a partir da srcDir do projeto se o pseudónimo @ for usado.

Os módulos devem exportar uma função para melhorar a construção e a execução e, opcionalmente, retornar uma promessa até o seu trabalho ser concluído. Notemos que são importados em execução, pelo que já devem ter sido traduzidos se utilizarem as funcionalidades modernas da ECMAScript 6.

Escrever o Nosso Próprio Módulo

Os módulos são funções. Podem ser empacotados como módulos de npm ou incluídos diretamente no código-fonte do nosso projeto:

export default {
  exampleMsg: 'hello',
  modules: [
    // Uso simples
    '~/modules/example',
    // Passar opções diretamente
    ['~/modules/example', { token: '123' }]
  ]
}

export default function ExampleModule(moduleOptions) {
  console.log(moduleOptions.token) // '123'
  console.log(this.options.exampleMsg) // 'hello'

  this.nuxt.hook('ready', async nuxt => {
    console.log('Nuxt is ready')
  })
}

// OBRIGATÓRIO se publicar o módulo como pacote de `npm`.
module.exports.meta = require('./package.json')

1) ModuleOptions

moduleOptions: este é o objeto passado pelo utilizador através do vetor modules. Podemos usá-lo para personalizar o seu comportamento.

Opções de Alto Nível

Por vezes é mais conveniente se pudermos utilizar opções de nível superior ao registar módulos no nuxt.config.js. Isto permite-nos combinar várias fontes de opções:

export default {
  modules: [['@nuxtjs/axios', { anotherOption: true }]],

  // o módulo `axios` está ciente disto ao usar `this.options.axios`
  axios: {
    option1,
    option2
  }
}

2) this.options

this.options: pode acessar diretamente às opções da Nuxt ao utilizar esta referência. Este é o conteúdo do nuxt.config.js do utilizador com todas as opções predefinidas atribuídas a este. Pode ser utilizado para opções partilhadas entre módulos:

export default function (moduleOptions) {
  // `options` conterá `option1`, `option2` e `anotherOption`.
  const options = Object.assign({}, this.options.axios, moduleOptions)

  // ...
}

Adicionar uma Biblioteca de Folha de Estilo

Se o nosso módulo fornecer uma biblioteca de folha de estilo em cascata, devemos certificar-nos de que verificamos se o utilizador já incluiu a biblioteca para evitar duplicações e adicionar uma opção para desativar a biblioteca de folha de estilo no módulo:

export default function (moduleOptions) {
  if (moduleOptions.fontAwesome !== false) {
    // Adicionar a `font-awesome`
    this.options.css.push('font-awesome/css/font-awesome.css')
  }
}

Emitir Recursos ou Ativos

Podemos registar as extensões da Webpack para emitir recursos durante a construção:

export default function (moduleOptions) {
    const info = 'Built by awesome module - 1.3 alpha on ' + Date.now()

    this.options.build.plugins.push({
        apply(compiler) {
            compiler.hooks.emit.tap('info-plugin', (compilation) => {
                compilation.assets['info.txt'] = {
                    source: () => info,
                    size: () => info.length
                }
            })
        }
    })
}

3) this.nuxt

this.nuxt: esta é uma referência para a instância atual da Nuxt. Podemos registar as funções gatilhos em certos eventos do ciclo de vida.

• Ready: A Nuxt está pronta para funcionar (ModuleContainer e Renderer prontos).

nuxt.hook('ready', async nuxt => {
  // Nosso código personalizado...
})

• Error: Um erro não tratado ao chamar funções gatilhos.

nuxt.hook('error', async error => {
  // Nosso código personalizado...
})

• Close: A instância da Nuxt fecha graciosamente.

nuxt.hook('close', async nuxt => {
  // Nosso código personalizado...
})

• Listen: O servidor interno da Nuxt começa a ouvir. (Ao utilizar o nuxt start ou nuxt dev).

nuxt.hook('listen', async (server, { host, port }) => {
  // Nosso código personalizado...
})

• this: contexto dos módulos. Todos os módulos serão chamados no contexto da instância da ModuleContainer.

Consultar a documentação da classe ModuleContainer por métodos disponíveis.

Executar Tarefas em Funções Gatilhos Específicas

O nosso módulo pode precisar de fazer coisas apenas em condições específicas e não apenas durante a inicialização da Nuxt. Podemos utilizar as poderosas funções gatilhos da Nuxt para realizar tarefas em eventos específicos (baseando na hookable ). A Nuxt aguardará por nossa função se esta retornar uma promessa ou for definida como async.

Eis alguns exemplos básicos:

export default function myModule() {
  this.nuxt.hook('modules:done', moduleContainer => {
    // Será chamada quando todos os módulos tiverem terminado o carregamento.
  })

  this.nuxt.hook('render:before', renderer => {
    // Chamada depois do desenhador ser criado.
  })

  this.nuxt.hook('build:compile', async ({ name, compiler }) => {
    // Chamada depois do compilador (predefinido como: webpack) iniciar.
  })

  this.nuxt.hook('generate:before', async generator => {
    // Será chamada antes da Nuxt gerar as nossas páginas.
  })
}

Fornecer Extensões

É comum que os módulos forneçam uma ou mais extensões quando adicionados. Por exemplo, o módulo bootstrap-vue teria de registar-se na Vue. Nestas situações, podemos utilizar a auxiliar this.addPlugin:

import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue/dist/bootstrap-vue.esm'

Vue.use(BootstrapVue)

import path from 'path'

export default function nuxtBootstrapVue(moduleOptions) {
  // Registar o molde `plugin.js`
  this.addPlugin(path.resolve(__dirname, 'plugin.js'))
}

Nota: quaisquer extensões injetadas por módulos são adicionadas ao início da lista de extensões. As nossas opções são:

• Adicionar manualmente a nossa extensão ao final da lista de extensões (this.nuxt.options.plugins.push(...))
• Inverter a ordem dos módulos se estes dependerem de outros.

Extensões do Molde de Conteúdo

Os moldes e as extensões registadas podem influenciar os moldes de conteúdo da lodash para alterar condicionalmente a saída das extensões registadas:

// Definir o Google Analytics UA
ga('create', '<%= options.ua %>', 'auto')

<% if (options.debug) { %>
// Exclusivo para código de desenvolvimento.
<% } %>

import path from 'path'

export default function nuxtGoogleAnalytics(moduleOptions) {
  // Registar o molde `plugin.js`
  this.addPlugin({
    src: path.resolve(__dirname, 'plugin.js'),
    options: {
      // A Nuxt substituirá `options.ua` por `123` ao copiar a extensão para o projeto.
      ua: 123,

      // Partes condicionais com `dev` serão retiradas do código da extensão nas construções de produção.
      debug: this.options.dev
    }
  })
}

Registar Carregadores Personalizados da Webpack

Podemos fazer o mesmo que build.extend no nuxt.config.js ao utilizar this.extendBuild:

export default function (moduleOptions) {
    this.extendBuild((config, { isClient, isServer }) => {
      // Carregador de `.foo`
      config.module.rules.push({
        test: /\.foo$/,
        use: [...]
      })

      // Personalizar carregadores existentes
      // Consultar o código-fonte para conhecer os componentes internos da Nuxt:
      // https://github.com/nuxt/nuxt/blob/2.x-dev/packages/webpack/src/config/base.js
      const barLoader = config.module.rules.find(rule => rule.loader === 'bar-loader')
  })
}

Módulos Assíncronos

Nem todos os módulos farão tudo de maneira síncrona. Por exemplo, podemos querer programar um módulo que precise de buscar dados de alguma interface de programação de aplicação ou fazer uma operação assíncrona. Para isto, a Nuxt suporta módulos assíncronos que podem retornar uma promessa ou chamar uma função de resposta.

Usar a async/await

import fse from 'fs-extra'

export default async function asyncModule() {
  // Podemos trabalhar de maneira assíncrona neste caso ao usar `async`/`await`.
  const pages = await fse.readJson('./pages.json')
}

Retornar uma Promessa

export default function asyncModule($http) {
  return $http
    .get('https://jsonplaceholder.typicode.com/users')
    .then(res => res.data.map(user => '/users/' + user.username))
    .then(routes => {
      // Estender as rotas da Nuxt
    })
}

Publicar o Nosso Módulo

module.exports.meta: esta linha é necessária se publicarmos o módulo como um pacote de npm. A Nuxt usa internamente a meta para trabalhar melhor com o nosso pacote:

module.exports.meta = require('./package.json')

buildModules

Alguns módulos só são importados durante o desenvolvimento e construção. Usar buildModules ajuda a acelerar a inicialização da produção e também diminui significativamente o tamanho dos nossos node_modules para implantações de produção. Consultar a documentação de cada módulo para ver se é recomendado utilizar modules ou buildModules.

A diferença de utilização é:

• Ao invés de adicionar modules dentro do nuxt.config.js, utilizar buildModules:

export default {
  buildModules: ['@nuxtjs/eslint-module']
}

• Ao invés de adicionar dependencies dentro do package.json, utilizar devDependencies:

yarn add --dev @nuxtjs/eslint-module

npm install --save-dev @nuxtjs/eslint-module

O nosso módulo é um buildModule a menos que:

• Fornece um serverMiddleware.
• Regista uma função gatilho de execução da Node.js (como sentry).
• Afeta o comportamento da vue-renderer ou utiliza uma função gatilho do espaço nominal server: ou vue-renderer.
• Qualquer outra coisa fora do âmbito de aplicação da Webpack (Dica: extensões e moldes são compilados e estão no âmbito de aplicação da Webpack).