|
| 1 | +# HMR `hotUpdate` Plugin Hook |
| 2 | + |
| 3 | +::: tip Feedback |
| 4 | +Give us feedback at [Environment API feedback discussion](https://github.com/vitejs/vite/discussions/16358) |
| 5 | +::: |
| 6 | + |
| 7 | +We're planning to deprecate the `handleHotUpdate` plugin hook in favor of [`hotUpdate` hook](/guide/api-environment#the-hotupdate-hook) to be [Environment API](/guide/api-environment.md) aware, and handle additional watch events with `create` and `delete`. |
| 8 | + |
| 9 | +Affected scope: `Vite Plugin Authors` |
| 10 | + |
| 11 | +::: warning Future Deprecation |
| 12 | +`hotUpdate` was first introduced in `v6.0`. The deprecation of `handleHotUpdate` is planned for `v7.0`. We don't yet recommend moving away from `handleHotUpdate` yet. If you want to experiment and give us feedback, you can use the `future.removePluginHookHandleHotUpdate` to `"warn"` in your vite config. |
| 13 | +::: |
| 14 | + |
| 15 | +## Motivation |
| 16 | + |
| 17 | +The [`handleHotUpdate` hook](/guide/api-plugin.md#handlehotupdate) allows to perform custom HMR update handling. A list of modules to be updated is passed in the `HmrContext` |
| 18 | + |
| 19 | +```ts |
| 20 | +interface HmrContext { |
| 21 | + file: string |
| 22 | + timestamp: number |
| 23 | + modules: Array<ModuleNode> |
| 24 | + read: () => string | Promise<string> |
| 25 | + server: ViteDevServer |
| 26 | +} |
| 27 | +``` |
| 28 | + |
| 29 | +This hook is called once for all environments, and the passed modules have mixed information from the Client and SSR environments only. Once frameworks move to custom environments, a new hook that is called for each of them is needed. |
| 30 | + |
| 31 | +The new `hotUpdate` hook works in the same way as `handleHotUpdate` but it is called for each environment and receives a new `HotUpdateContext` instance: |
| 32 | + |
| 33 | +```ts |
| 34 | +interface HotUpdateContext { |
| 35 | + type: 'create' | 'update' | 'delete' |
| 36 | + file: string |
| 37 | + timestamp: number |
| 38 | + modules: Array<EnvironmentModuleNode> |
| 39 | + read: () => string | Promise<string> |
| 40 | + server: ViteDevServer |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +The current dev environment can be accessed like in other Plugin hooks with `this.environment`. The `modules` list will now be module nodes from the current environment only. Each environment update can define different update strategies. |
| 45 | + |
| 46 | +This hook is also now called for additional watch events and not only for `'update'`. Use `type` to differentiate between them. |
| 47 | + |
| 48 | +## Migration Guide |
| 49 | + |
| 50 | +Filter and narrow down the affected module list so that the HMR is more accurate. |
| 51 | + |
| 52 | +```js |
| 53 | +handleHotUpdate({ modules }) { |
| 54 | + return modules.filter(condition) |
| 55 | +} |
| 56 | + |
| 57 | +// Migrate to: |
| 58 | + |
| 59 | +hotUpdate({ modules }) { |
| 60 | + return modules.filter(condition) |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +Return an empty array and perform a full reload: |
| 65 | + |
| 66 | +```js |
| 67 | +handleHotUpdate({ server, modules, timestamp }) { |
| 68 | + // Invalidate modules manually |
| 69 | + const invalidatedModules = new Set() |
| 70 | + for (const mod of modules) { |
| 71 | + server.moduleGraph.invalidateModule( |
| 72 | + mod, |
| 73 | + invalidatedModules, |
| 74 | + timestamp, |
| 75 | + true |
| 76 | + ) |
| 77 | + } |
| 78 | + server.ws.send({ type: 'full-reload' }) |
| 79 | + return [] |
| 80 | +} |
| 81 | + |
| 82 | +// Migrate to: |
| 83 | + |
| 84 | +hotUpdate({ modules, timestamp }) { |
| 85 | + // Invalidate modules manually |
| 86 | + const invalidatedModules = new Set() |
| 87 | + for (const mod of modules) { |
| 88 | + this.environment.moduleGraph.invalidateModule( |
| 89 | + mod, |
| 90 | + invalidatedModules, |
| 91 | + timestamp, |
| 92 | + true |
| 93 | + ) |
| 94 | + } |
| 95 | + this.environment.hot.send({ type: 'full-reload' }) |
| 96 | + return [] |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +Return an empty array and perform complete custom HMR handling by sending custom events to the client: |
| 101 | + |
| 102 | +```js |
| 103 | +handleHotUpdate({ server }) { |
| 104 | + server.ws.send({ |
| 105 | + type: 'custom', |
| 106 | + event: 'special-update', |
| 107 | + data: {} |
| 108 | + }) |
| 109 | + return [] |
| 110 | +} |
| 111 | + |
| 112 | +// Migrate to... |
| 113 | + |
| 114 | +hotUpdate() { |
| 115 | + this.environment.hot.send({ |
| 116 | + type: 'custom', |
| 117 | + event: 'special-update', |
| 118 | + data: {} |
| 119 | + }) |
| 120 | + return [] |
| 121 | +} |
| 122 | +``` |
0 commit comments