Nuxt 3 Release Candidate is out! Discover more about it on v3.nuxtjs.org

Page traduite Le contenu de cette page peut être déprécié.

plugins

Le répertoire plugins contient les plugins JavaScript que l'on souhaite exécuter avant l'instanciation de l'application principale Vue.js.


Le répertoire plugins contient les plugins JavaScript que l'on souhaite exécuter avant l'instanciation de l'application principale Vue.js. C'est ici que l'on peut ajouter des plugins Vue.js et injecter des fonctions/constantes. À chaque fois que l'on a besoin d'utiliser Vue.use(), on peut créer un fichier dans plugins/ et ajouter son chemin à la propriété plugins dans le fichier nuxt.config.js.

Packages externes

On pourrait avoir envie d'utiliser des packages/modules externes dans notre application (ex: axios ) pour faire des requêtes HTTP côté client et serveur.

Premièrement, l'installer via npm ou Yarn.

Yarn
yarn add @nuxtjs/axios
NPM
npm install @nuxtjs/axios

On peut par exemple configurer les intercepteurs d'axios pour réagir à de possibles erreurs lorsque l'on fait des appels à notre API et ce, à travers toute notre application. Dans l'exemple suivant, on redirige l'utilisateur sur une page d'erreur personnalisée appelée sorry lorsque l'on obtient un code d'erreur 500 de la part de notre API.

plugins/axios.js
export default function ({ $axios, redirect }) {
  $axios.onError(error => {
    if (error.response.status === 500) {
      redirect('/sorry')
    }
  })
}

Il faut par la suite ajouter le module et les plugins fraîchement créés dans la configuration du projet.

nuxt.config.js
module.exports = {
  modules: ['@nuxtjs/axios'],
  plugins: ['~/plugins/axios.js']
}

Ensuite, on pourra l'utiliser directement dans nos composants page:

pages/index.vue
<template>
  <h1>{{ post.title }}</h1>
</template>

<script>
export default {
    async asyncData ({ $axios, params }) {
        const  post  = await $axios.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
        return { post }
      }
}
</script>
Si une erreur Cannot use import statement outside a module apparaît, ajoutez votre package dans l'option build > transpile du ficher nuxt.config.js pour rendre votre plugin disponible au loader webpack.
nuxt.config.js
build: {
  // Etendez votre configuration webpack ici
  transpile: ['npm-package-name'],
},

Plugins Vue

Si on veut utiliser des plugins Vue.js, comme par exemple v-tooltip pour afficher des tooltips dans notre application, nous avons besoin de configurer le plugin avant de lancer l'application.

Commençons par l'installer

Yarn
yarn add v-tooltip
NPM
npm install v-tooltip

Ensuite, créons le fichier plugins/vue-tooltip.js

plugins/vue-tooltip.js
import Vue from 'vue'
import VTooltip from 'v-tooltip'

Vue.use(VTooltip)

La propriété plugins

Ensuite nous pouvons ajouter le chemin du fichier à l'intérieur de la propriété plugins du fichier nuxt.config.js. La propriété plugins permet d'ajouter facilement des plugins Vue.js à notre application principale. Tous les chemins définis dans la propriété plugins seront importés avant d'initialiser l'application principale.

nuxt.config.js
export default {
  plugins: ['~/plugins/vue-tooltip.js']
}

Plugins ES6

Si le plugin est situé dans les node_modules et qu'il exporte un module en ES6, nous aurons besoin de l'ajouter à l'option de build transpile:

nuxt.config.js
module.exports = {
  build: {
    transpile: ['vue-tooltip']
  }
}

Pour davantage d'informations sur les options, veuillez vous référer à la configuration du build .

Côté client ou serveur seulement

Certains plugins ne devraient fonctionner que dans le navigateur car ils n'auront pas de support SSR (Server Side Rendering).

Convention pour le nommage des plugins

Si un plugin est voué à être exécuté seulement du côté client ou seulement du côté serveur, on peut appliquer une extension .client.js ou .server.js à l'extension du fichier du plugin. Le fichier sera automatiquement inclus du côté client ou serveur seulement (respectivement).

nuxt.config.js
export default {
  plugins: [
    '~/plugins/foo.client.js', // seulement du côté client
    '~/plugins/bar.server.js', // seulement du côté serveur
    '~/plugins/baz.js' // sur le serveur et sur le client
  ]
}

Syntaxe objet

On peut aussi utiliser la syntaxe objet avec la propriété mode ('client'  ou 'server') dans plugins.

nuxt.config.js
export default {
  plugins: [
    { src: '~/plugins/both-sides.js' }, // sur le serveur et sur le client
    { src: '~/plugins/client-only.js', mode: 'client' }, // seulement du côté client
    { src: '~/plugins/server-only.js', mode: 'server' } // seulement du côté serveur
  ]
}

Injection dans le $root et le context

Parfois, on souhaiterait rendre des fonctions ou des variables accessibles dans l'intégralité de notre application. On peut injecter ces variables dans notre instance Vue (côté client), dans le context (côté serveur) et même dans le store Vuex. La convention pour le préfixe des fonctions que l'on a injecté est $.

Nuxt nous fournit une méthode inject(cle, valeur) pour faire cela facilement. Le second paramètre donné à inject est la fonction que l'on souhaite exporter. Le $ sera automatiquement préfixé à notre clé.

Il est important de savoir que dans tout lifecycle d'une instance Vue, seulement les hooks beforeCreate et created seront appellés du côté client et serveur. Les hooks restants seront appellés seulement du côté client.
plugins/hello.js
export default ({ app }, inject) => {
  // Ceci injecte $hello(msg) dans Vue, dans le context et le store.
  inject('hello', msg => console.log(`Hello ${msg}!`))
}
nuxt.config.js
export default {
  plugins: ['~/plugins/hello.js']
}

Maintenant le service $hello est accessible depuis le context et this dans les pages, les composants, les plugins, et les actions du store.

example-component.vue
export default {
  mounted() {
    this.$hello('mounted')
    // Va console.log 'Hello mounted!'
  },
  asyncData({ app, $hello }) {
    $hello('asyncData')
    // Si la version de Nuxt <= 2.12, il faut utiliser 👇
    app.$hello('asyncData')
  }
}
store/index.js
export const state = () => ({
  someValue: ''
})

export const actions = {
  setSomeValueToWhatever({ commit }) {
    this.$hello('store action')
    const newValue = 'whatever'
    commit('changeSomeValue', newValue)
  }
}
Il faut bien faire attention à ne pas utiliser Vue.use(), Vue.component() ou quoi que ce soit d'autre lié à Vue à l'intérieur de cette fonction dédiée à l'injection de Nuxt. Sinon, cela causerait des fuites de mémoire côté serveur.

La propriété extendPlugins

On pourrait avoir envie de personnaliser les plugins ou changer l'ordre des plugins créé par Nuxt. Cette fonction accepte un tableau d'objets plugins et retourne la même chose, réarrangé.

Un exemple de changement de l'ordre des plugins:

nuxt.config.js
export default {
  extendPlugins(plugins) {
    const pluginIndex = plugins.findIndex(
      ({ src }) => src === '~/plugins/shouldBeFirst.js'
    )
    const shouldBeFirstPlugin = plugins[pluginIndex]

    plugins.splice(pluginIndex, 1)
    plugins.unshift(shouldBeFirstPlugin)

    return plugins
  }
}

Mixins globaux

Des mixins globaux peuvent être facilement ajoutés aux plugins de Nuxt mais peuvent causer des soucis et des fuites de mémoire s'ils sont mal gérés. À chaque fois que l'on ajoute un mixin global à l'application, if faut bien faire attention à lui passer un flag pour éviter de l'enregistrer plusieurs fois:

plugins/my-mixin-plugin.js
import Vue from "vue"

// Assurez-vous de choisir un nom unique pour le drapeau
// il n'y aura donc pas de conflit avec aucun autre mixin.
if (!Vue.__my_mixin__) {
    Vue.__my__mixin__ = true
  Vue.mixin({ ... }) // On peut ensuite configurer le mixin
}