HMR API #

Note :::tip Il s'agit de l'API HMR client. Pour gérer les mises à jour HMR dans les plugins, voir handleHotUpdate.

L'API HMR manuelle est principalement destinée aux auteurs de frameworks et d'outils. En tant qu'utilisateur final, HMR est probablement déjà géré pour vous dans les modèles de démarrage spécifiques au framework. :: :

Vite expose son API HMR manuelle via l'objet spécial import.meta.hot :

interface ImportMeta {
  readonly hot ? ViteHotContext
}

type ModuleNamespace = Record<string, any> & {
  [Symbol.toStringTag] : "Module" [Symbol.toStringTag] : "Module".
}

interface ViteHotContext {
  readonly data : any

  accept() : void
  accept(cb : (mod : ModuleNamespace | undefined) => void) : void
  accept(dep : string, cb : (mod : ModuleNamespace | undefined) => void) : void
  accept(
    deps : string[] en lecture seule,
    cb : (mods : Array<ModuleNamespace | undefined>) => void
  ) : void

  dispose(cb : (data : any) => void) : void
  decline() : void
  invalidate() : void

  // `InferCustomEventPayload` fournit des types pour les évènements Vite intégrés
  on<T extends string>(
    événement : T,
    cb : (payload : InferCustomEventPayload<T>) => void
  ) : void
  send<T extends string>(event : T, data? : InferCustomEventPayload<T>) : void
}

Garde conditionnelle obligatoire #

Tout d'abord, assurez-vous de protéger toute utilisation de l'API HMR avec un bloc conditionnel afin que le code puisse être secoué en production :

``js if (import.meta.hot) { // Code HMR }

## `hot.accept(cb)`

Pour qu'un module s'auto-accepte, utilisez `import.meta.hot.accept` avec un callback qui reçoit le module mis à jour :

``js
export const count = 1

if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    if (nouveauModule) {
      // newModule est indéfini au moment de l'apparition de la SyntaxError
      console.log('updated : count is now ', newModule.count)
    }
  })
}

Un module qui "accepte" les mises à jour à chaud est considéré comme une limite HMR.

Notez que le HMR de Vite n'échange pas réellement le module importé à l'origine : si un module limite HMR réexporte les importations d'un dep, alors il est responsable de la mise à jour de ces réexportations (et ces exportations doivent utiliser let). De plus, les importateurs en amont du module limite ne seront pas informés du changement.

Cette implémentation simplifiée de HMR est suffisante pour la plupart des cas d'utilisation du développement, tout en nous permettant d'éviter le travail coûteux de génération de modules proxy.

hot.accept(deps, cb) #

Un module peut également accepter les mises à jour des dépendances directes sans se recharger lui-même :

``js Importez { foo } de './foo.js'.

foo()

if (import.meta.hot) { import.meta.hot.accept('./foo.js', (newFoo) => { // la callback reçoit le module './foo.js' mis à jour nouveauFoo ?.foo() })

// Peut également accepter un tableau de modules dep : import.meta.hot.accept( ['./foo.js', './bar.js'], ([newFooModule, newBarModule]) => { // le callback reçoit les modules mis à jour dans un Array } ) }

## `hot.dispose(cb)`

Un module qui s'accepte lui-même ou un module qui s'attend à être accepté par d'autres peut utiliser `hot.dispose` pour nettoyer tous les effets secondaires persistants créés par sa copie mise à jour :

``js
function setupSideEffect() {}

setupSideEffect()

if (import.meta.hot) {
  import.meta.hot.dispose((data) => {
    // nettoyage de l'effet secondaire
  })
}

hot.data #

L'objet import.meta.hot.data est conservé entre différentes instances du même module mis à jour. Il peut être utilisé pour transmettre des informations d'une version précédente du module à la suivante.

hot.decline() #

L'appel à import.meta.hot.decline() indique que ce module n'est pas hot-updatable et que le navigateur doit effectuer un rechargement complet si ce module est rencontré lors de la propagation des mises à jour HMR.

hot.invalidate() #

Un module auto-acceptable peut se rendre compte pendant l'exécution qu'il ne peut pas gérer une mise à jour HMR, et donc la mise à jour doit être propagée de force aux importateurs. En appelant import.meta.hot.invalidate(), le serveur HMR invalidera les importateurs de l'appelant, comme si l'appelant n'était pas auto-acceptable.

Notez que vous devriez toujours appeler import.meta.hot.accept même si vous prévoyez d'appeler invalidate immédiatement après, sinon le client HMR n'écoutera pas les changements futurs du module auto-acceptable. Pour communiquer clairement votre intention, nous vous recommandons d'appeler invalidate à l'intérieur du callback accept comme ceci :

``js import.meta.hot.accept((module) => { // Vous pouvez utiliser la nouvelle instance du module pour décider de l'invalidation. if (cannotHandleUpdate(module)) { import.meta.hot.invalidate() } })

## `hot.on(event, cb)``

Écoute un événement HMR.

Les événements HMR suivants sont distribués automatiquement par Vite :

- `'vite:beforeUpdate'` lorsqu'une mise à jour est sur le point d'être appliquée (par exemple, un module va être remplacé)
- vite:beforeFullReload'` lorsqu'un rechargement complet est sur le point de se produire
- vite:beforePrune'` lorsque les modules qui ne sont plus nécessaires sont sur le point d'être élagués
- `'vite:invalidate'` lorsqu'un module est invalidé avec `import.meta.hot.invalidate()`
- `'vite:error'` lorsqu'une erreur se produit (par exemple, une erreur de syntaxe)

Des événements HMR personnalisés peuvent également être envoyés par des plugins. Voir [handleHotUpdate](./api-plugin#handlehotupdate) pour plus de détails.

## `hot.send(event, data)`

Envoyez des événements personnalisés au serveur de développement de Vite.

Si appelé avant d'être connecté, les données seront mises en mémoire tampon et envoyées une fois la connexion établie.

Voir [Communication client-serveur](/guide/api-plugin.html#client-server-communication) pour plus de détails.