Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(hmr): improve handleHotUpdate and add further reading #15996

Merged
merged 1 commit into from
Feb 21, 2024
Merged

docs(hmr): improve handleHotUpdate and add further reading #15996

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/guide/api-hmr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,3 +206,9 @@ Send custom events back to Vite's dev server.
If called before connected, the data will be buffered and sent once the connection is established.

See [Client-server Communication](/guide/api-plugin.html#client-server-communication) for more details.

## Further Reading

If you'd like to learn more about how to use the HMR API and how it works under-the-hood. Check out these resources:

- [Hot Module Replacement is Easy](https://bjornlu.com/blog/hot-module-replacement-is-easy)
24 changes: 23 additions & 1 deletion docs/guide/api-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -402,6 +402,7 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo
### `handleHotUpdate`

- **Type:** `(ctx: HmrContext) => Array<ModuleNode> | void | Promise<Array<ModuleNode> | void>`
- **See also:** [HMR API](./api-hmr)

Perform custom HMR update handling. The hook receives a context object with the following signature:

Expand All @@ -423,10 +424,31 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo

- Filter and narrow down the affected module list so that the HMR is more accurate.

- Return an empty array and perform complete custom HMR handling by sending custom events to the client (example uses `server.hot` which was introduced in Vite 5.1, it is recommended to also use `server.ws` if you support lower versions):
- Return an empty array and perform a full reload:

```js
handleHotUpdate({ server, modules, timestamp }) {
// Also use `server.ws.send` to support Vite <5.1 if needed
server.hot.send({ type: 'full-reload' })
// Invalidate modules manually
const invalidatedModules = new Set()
for (const mod of modules) {
server.moduleGraph.invalidateModule(
mod,
invalidatedModules,
timestamp,
true
)
}
Comment on lines +433 to +442
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally I think, we shouldn't need to have user invalidate this way. This line

vite/packages/vite/src/node/server/index.ts

Lines 723 to 724 in e4ea7dd

// invalidate module graph cache on file change
moduleGraph.onFileChange(file)

Should already cover the invalidation, but this code here is to also invalidate for HMR (forth param). The param is used for

vite/packages/vite/src/node/server/moduleGraph.ts

Lines 186 to 192 in e4ea7dd

if (isHmr) {
mod.lastHMRTimestamp = timestamp
} else {
// Save the timestamp for this invalidation, so we can avoid caching the result of possible already started
// processing being done for this module
mod.lastInvalidationTimestamp = timestamp
}

But I was thinking of combining the two timestamps in the future. And then we can remove the HMR param.

return []
}
```

- Return an empty array and perform complete custom HMR handling by sending custom events to the client:

```js
handleHotUpdate({ server }) {
// Also use `server.ws.send` to support Vite <5.1 if needed
server.hot.send({
type: 'custom',
event: 'special-update',
Expand Down