You are browsing Nuxt 2 docs. Go to Nuxt 3 docs, or learn more about Nuxt 2 Long Term Support.

Translated page Contents of this page might be outdated.

O diretório modules

O Nuxt fornece um sistema de módulo de alta ordem que torna possível estender o núcleo. Os módulos são funções que são chamados sequencialmente sempre o Nuxt estiver iniciando.


Explorando os módulos do Nuxt

Descubra nossa lista de módulos para super carregar o seu projeto Nuxt, criado pela equipa do Nuxt e pela comunidade.

  • 165+ Módulos
  • 105+ Mantenedores

Enquanto estiver desenvolvendo aplicações para produção com Nuxt você pode achar que o núcleo de funcionalidade do framework não é suficiente. O Nuxt pode ser estendido com opções de configuração e plugins, mas manter essas personalizações através de vários projetos é tedioso, repetitivo e consume tempo. Por outro lado, atender a cada necessidade do projeto fora da caixa tornaria o Nuxt muito complexo e difícil de usar.

Esta é uma das razões do porquê o Nuxt fornecer um sistema de módulo de alta ordem que torna possível estender o núcleo. Os módulos são funções que são chamados sequencialmente sempre o Nuxt estiver iniciando. O framework espera cada módulo terminar antes de continuar. Desta maneira, os módulos podem personalizar quase qualquer aspeto da sua aplicação. Graças o desenho modular do Nuxt (baseado no Tapable do webpack), os módulos podem facilmente registar gatilhos para certos pontos de entrada como a inicialização do construtor. Os módulos podem também sobrescrever modelos, configurar os carregadores do webpack, adicionar bibliotecas CSS, e realizar muitas outras tarefas úteis.

O melhor de tudo, os módulos do Nuxt podem ser incorporados dentro dos pacotes npm. Isto torna possível re-usar através dos projetos e partilhar com a comunidade, ajudando a criar um ecossistema de recursos adicionáveis de alta qualidade.

A propriedade modules

Os módulos são extensões do Nuxt que podem estender a funcionalidade do núcleo do framework e adicionar integrações sem fim. Uma vez você ter instalado os módulos você pode então adicionar eles ao seu ficheiro nuxt.config.js dentro da propriedade modules.

nuxt.config.js
export default {
  modules: [
    // Usando o nome do pacote
    '@nuxtjs/axios',

    // Relativo ao diretório fonte do seu projeto (srcDir)
    '~/modules/awesome.js',

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

    // Definição em linha
    function () {}
  ]
}
Desenvolvedores de módulo geralmente fornecem passos adicionais necessários e detalhes para utilização.

O Nuxt tenta resolver cada item dentro do array de módulos usando o caminho exigido pelo node (dentro do node_modules) e depois resolverá a partir do srcDir se o apelido @ for usado.

Os módulos são executados sequencialmente, então a ordem é importante.

Os módulos devem exportar uma função para destacar a construção/tempo de execução e opcionalmente retorna uma promessa até que o trabalho deles esteja terminado. Repare que eles são importados em tempo de execução então eles devem já estar transpilados se estiverem usando as funcionalidades modernas do ES6.

Escreva o seu próprio módulo

Os módulos são funções. Eles podem ser empacotados como módulos npm ou diretamente incluídos dentro do código-fonte do seu projeto.

nuxt.config.js
export default {
  exampleMsg: 'hello',
  modules: [
    // Uso símples
    '~/modules/example',
    // Passando as opções diretamente
    ['~/modules/example', { token: '123' }]
  ]
}
modules/example.js
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 estiver publicando o módulo como pacote npm
module.exports.meta = require('./package.json')

1) ModuleOptions

moduleOptions: este é o objeto passado usando o array modules pelo usuário. Podemos usar ele para personalizar seu comportamento,

Opções de alto nível

Algumas vezes é muito mais conveniente podermos usar opções de alto nível enquanto estivermos registando módulos dentro do nuxt.config.js. Isto permite-nos combinar várias fontes de opções.

nuxt.config.js
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: Você pode acessar diretamente as opções do Nuxt usando esta referência. Este é o conteúdo do nuxt.config.js do usuário com todas opções padrão atribuídas a ela. Ela pode ser usada para opções partilhadas entre os módulos.

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

  // ...
}

Adicionar uma biblioteca CSS

Se o seu módulo fornecerá uma biblioteca CSS, certifique-se de realizar uma verificação para saber se o usuário já incluiu a biblioteca para evitar, e adicionar uma opção para desativar a biblioteca CSS dentro do módulo.

module.js
export default function (moduleOptions) {
  if (moduleOptions.fontAwesome !== false) {
    // Adicione o font-awesome
    this.options.css.push('font-awesome/css/font-awesome.css')
  }
}

Emitir os recursos

Nós podemos registar os plugins do webpack para emitir os recursos durante a construção.

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

  this.options.build.plugins.push({
    apply(compiler) {
      compiler.plugin('emit', (compilation, cb) => {
        // Isto gerará o `.nuxt/dist/info.txt' com os conteúdos da variável info.
        // A fonte (source) pode ser uma memória temporária também.
        compilation.assets['info.txt'] = {
          source: () => info,
          size: () => info.length
        }

        cb()
      })
    }
  })
}

3) this.nuxt

this.nuxt: Isto é uma referência a instância atual do Nuxt. Nós podemos registar gatilhos em certos eventos do ciclo de vida.

  • Ready : O Nuxt está pronto para trabalhar (ModuleContainer e Renderer prontos).
nuxt.hook('ready', async nuxt => {
  // O seu código personalizado vai aqui
})
  • Error: Um erro não manipulado quando estiver chamando os gatilhos.
nuxt.hook('error', async error => {
  // O seu código personalizado vai aqui
})
  • Close: A instância do Nuxt está fechando graciosamente.
nuxt.hook('close', async nuxt => {
  // O seu código personalizado vai aqui
})
  • Listen: O servidor interno do Nuxt começa ouvindo. (Usando o nuxt start ou nuxt dev)
nuxt.hook('listen', async (server, { host, port }) => {
  // O seu código personalizado vai aqui
})

this: O contexto dos módulos. Todos os módulos são chamados dentro contexto da instância ModuleContainer.

Consulte a documentação da classe ModuleContainer para conhecer os métodos disponíveis.

Executar tarefas em gatilhos específicos

O seu módulo pode precisar fazer coisas apenas sobre condições específicas e não somente durante a inicialização do Nuxt. Nós podemos usar os poderosos gatilhos do Nuxt para realizar tarefas em eventos específicos (baseado no Hookable ). O Nuxt esperará pela sua função para saber se ela retorna uma promessa ou está definida como async.

Here are some basic examples:

modules/myModule.js
export default function myModule() {
  this.nuxt.hook('modules:done', moduleContainer => {
    // Isto será chamado quando todos os módulos terminarem o carregamento
  })

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

  this.nuxt.hook('build:compile', async ({ name, compiler }) => {
    // Chamado antes do compilador (padrão: webpack) começar
  })

  this.nuxt.hook('generate:before', async generator => {
    // Isto será chamado antes do Nuxt gerar suas páginas
  })
}

Fornecer plugins

É comum que módulos forneçam um ou mais plugins quando adicionados. Por exemplo o módulo bootstrap-vue precisaria registar a si mesmo dentro do Vue. Em tais situações nós podemos usar o auxiliar this.addPlugin.

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

Vue.use(BootstrapVue)
module.js
import path from 'path'

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

Observe que: Quaisquer plugins injetados pelos módulos são adicionados no princípio da lista lista de plugins. Suas opções são:

  • Manualmente adicionar o plugin para o final da lista de plugins (this.nuxt.options.plugins.push(...))
  • Inverter a ordem dos módulos se ele depender de um outro

Os plugins do modelo

Os modelos registados e plugins podem influenciar o os modelos do lodash para condicionalmente mudar a saída dos plugins registados.

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

<% if (options.debug) { %>
// Apenas código do desenvolvedor
<% } %>
module.js
import path from 'path'

export default function nuxtGoogleAnalytics(moduleOptions) {
  // Registar o modelo `plugin.js`
  this.addPlugin({
    src: path.resolve(__dirname, 'plugin.js'),
    options: {
      // O Nuxt substituirá `options.ua` com `123` quando estiver copiando o plugin para o projeto
      ua: 123,

      // partes condicionais com `dev` será desfeito do código do plugin nas construções de produção
      debug: this.options.dev
    }
  })
}

Registar carregadores personalizados do webpack

Nós podemos fazer o mesmo com o build.extend dentro do nuxt.config.js usando this.extendBuild.

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

      // Personalizar carregadores existentes
      // Recorra ao código-fonte para o interior do 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')
  })
}

Os módulos assíncronos

Nem todos os módulos farão tudo de forma síncrona. Por exemplo, você talvez queira desenvolver um módulo que precisar requisitar alguma API ou fazer operações assíncronas. Para isto, o Nuxt suporta módulos assíncronos que podem retornar uma promessa ou chamar um callback.

Use o async/await

import fse from 'fs-extra'

export default async function asyncModule() {
  // Você pode fazer trabalho assíncrono aqui usando `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 => {
      // Faça alguma coisa ao estender as rotas do nuxt
    })
}
Existem mais gatilhos e possibilidades para módulos. Consulte o Interior do Nuxt para achar mais informações sobre a API nuxt-internal.

Publicando o seu módulo

module.exports.meta: Esta linha é exigida se você estiver publicando o módulo como um pacote npm. O Nuxt usa internamente o meta para trabalhar melhor com seu pacote.

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

A propriedade buildModules

Alguns módulos são apenas importados durante o tempo de desenvolvimento e construção. Usar buildModules ajuda tornar inicio da produção rápido e também diminuir significativamente o tamanho do seu diretório node_modules para deployments em produção. Recorra à documentação para cada módulo para ver se é recomendado usar a propriedade modules ou buildModules.

A diferença de uso é:

  • Ao invés de adicionar ao modules dentro do nuxt.config.js, adicione ao buildModules
nuxt.config.js
export default {
  buildModules: ['@nuxtjs/eslint-module']
}
  • Ao invés de adicionar ao dependencies dentro do package.json, adicione ao devDependencies
Yarn
yarn add --dev @nuxtjs/eslint-module
NPM
npm install --save-dev @nuxtjs/eslint-module
Se você é um autor de módulo, é altamente recomendado sugerir aos usuários que instalem o seu pacote como uma devDependency e usar o buildModules ao invés de modules para o nuxt.config.js.

O seu módulo é um buildModules a menos que:

  • Ele esteja fornecendo um serverMiddleware
  • Ele tem de registar um gatilho para o tempo de execução do Node.js (como sentry)
  • Ele esteja afetando o comportamento do vue-renderer ou usando um gatilho do espaço de nome server: ou vue-renderer
  • Outra coisa que esteja fora do escopo do webpack (sugestão: plugins e modelos que são compilados e estão dentro do escopo do webpack)
Se você está oferecendo o uso do buildModules mencione que esta funcionalidade está apenas disponível a partir da versão 2.9 do Nuxt. Usuários antigos devem atualizar ou usar a secção modules.