feat: support import.meta.hot.invalidate (#10244)

Co-authored-by: Alec Larson <[email protected]>
Co-authored-by: 翠 / green <[email protected]>

docs/guide/api-hmr.md

@@ -125,7 +125,18 @@ Calling `import.meta.hot.decline()` indicates this module is not hot-updatable,
 
 ## `hot.invalidate()`
 
-For now, calling `import.meta.hot.invalidate()` simply reloads the page.
+A self-accepting module may realize during runtime that it can't handle a HMR update, and so the update needs to be forcefully propagated to importers. By calling `import.meta.hot.invalidate()`, the HMR server will invalidate the importers of the caller, as if the caller wasn't self-accepting.
+
+Note that you should always call `import.meta.hot.accept` even if you plan to call `invalidate` immediately afterwards, or else the HMR client won't listen for future changes to the self-accepting module. To communicate your intent clearly, we recommend calling `invalidate` within the `accept` callback like so:
+
+ ```ts
+ import.meta.hot.accept(module => {
+ // You may use the new module instance to decide whether to invalidate.
+ if (cannotHandleUpdate(module)) {
+ import.meta.hot.invalidate()
+ }
+ })
+ ```
 
 ## `hot.on(event, cb)`
 
@@ -136,6 +147,7 @@ The following HMR events are dispatched by Vite automatically:
 - `'vite:beforeUpdate'` when an update is about to be applied (e.g. a module will be replaced)
 - `'vite:beforeFullReload'` when a full reload is about to occur
 - `'vite:beforePrune'` when modules that are no longer needed are about to be pruned
+- `'vite:invalidate'` when a module is invalidated with `import.meta.hot.invalidate()`
 - `'vite:error'` when an error occurs (e.g. syntax error)
 
 Custom HMR events can also be sent from plugins. See [handleHotUpdate](./api-plugin#handlehotupdate) for more details.

packages/vite/src/client-types.d.ts

@@ -1,6 +1,7 @@
 export type {
  CustomEventMap,
- InferCustomEventPayload
+ InferCustomEventPayload,
+ InvalidatePayload
 } from './types/customEvent'
 export type {
  HMRPayload,

packages/vite/src/client/client.ts

@@ -546,10 +546,10 @@ export function createHotContext(ownerPath: string): ViteHotContext {
  // eslint-disable-next-line @typescript-eslint/no-empty-function
  decline() {},
 
+ // tell the server to re-perform hmr propagation from this module as root
  invalidate() {
- // TODO should tell the server to re-perform hmr propagation
- // from this module as root
- location.reload()
+ notifyListeners('vite:invalidate', { path: ownerPath })
+ this.send('vite:invalidate', { path: ownerPath })
  },
 
  // custom events

packages/vite/src/node/index.ts

@@ -102,7 +102,11 @@ export type {
  PrunePayload,
  ErrorPayload
 } from 'types/hmrPayload'
-export type { CustomEventMap, InferCustomEventPayload } from 'types/customEvent'
+export type {
+ CustomEventMap,
+ InferCustomEventPayload,
+ InvalidatePayload
+} from 'types/customEvent'
 // [deprecated: use vite/client/types instead]
 export type {
  ImportGlobFunction,

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

@@ -13,6 +13,7 @@ import launchEditorMiddleware from 'launch-editor-middleware'
 import type { SourceMap } from 'rollup'
 import picomatch from 'picomatch'
 import type { Matcher } from 'picomatch'
+import type { InvalidatePayload } from 'types/customEvent'
 import type { CommonServerOptions } from '../http'
 import {
  httpServerStart,
@@ -67,7 +68,12 @@ import { timeMiddleware } from './middlewares/time'
 import { ModuleGraph } from './moduleGraph'
 import { errorMiddleware, prepareError } from './middlewares/error'
 import type { HmrOptions } from './hmr'
-import { handleFileAddUnlink, handleHMRUpdate } from './hmr'
+import {
+ getShortName,
+ handleFileAddUnlink,
+ handleHMRUpdate,
+ updateModules
+} from './hmr'
 import { openBrowser } from './openBrowser'
 import type { TransformOptions, TransformResult } from './transformRequest'
 import { transformRequest } from './transformRequest'
@@ -489,6 +495,14 @@ export async function createServer(
  handleFileAddUnlink(normalizePath(file), server)
  })
 
+ ws.on('vite:invalidate', async ({ path }: InvalidatePayload) => {
+ const mod = moduleGraph.urlToModuleMap.get(path)
+ if (mod && mod.isSelfAccepting && mod.lastHMRTimestamp > 0) {
+ const file = getShortName(mod.file!, config.root)
+ updateModules(file, [...mod.importers], mod.lastHMRTimestamp, server)
+ }
+ })
+
  if (!middlewareMode && httpServer) {
  httpServer.once('listening', () => {
  // update actual port since this may be different from initial value

packages/vite/src/types/customEvent.d.ts

@@ -10,6 +10,11 @@ export interface CustomEventMap {
  'vite:beforePrune': PrunePayload
  'vite:beforeFullReload': FullReloadPayload
  'vite:error': ErrorPayload
+ 'vite:invalidate': InvalidatePayload
+}
+
+export interface InvalidatePayload {
+ path: string
 }
 
 export type InferCustomEventPayload<T extends string> =

packages/vite/types/customEvent.d.ts

@@ -1 +1,5 @@
-export type { CustomEventMap, InferCustomEventPayload } from '../client/types'
+export type {
+ CustomEventMap,
+ InferCustomEventPayload,
+ InvalidatePayload
+} from '../client/types'

playground/hmr/__tests__/hmr.spec.ts

@@ -18,14 +18,14 @@ test('should render', async () => {
 
 if (!isBuild) {
  test('should connect', async () => {
- expect(browserLogs.length).toBe(2)
+ expect(browserLogs.length).toBe(3)
  expect(browserLogs.some((msg) => msg.match('connected'))).toBe(true)
  browserLogs.length = 0
  })
 
  test('self accept', async () => {
  const el = await page.$('.app')
-
+ browserLogs.length = 0
  editFile('hmr.ts', (code) => code.replace('const foo = 1', 'const foo = 2'))
  await untilUpdated(() => el.textContent(), '2')
 
@@ -91,6 +91,7 @@ if (!isBuild) {
 
  test('nested dep propagation', async () => {
  const el = await page.$('.nested')
+ browserLogs.length = 0
 
  editFile('hmrNestedDep.js', (code) =>
  code.replace('const foo = 1', 'const foo = 2')
@@ -127,6 +128,25 @@ if (!isBuild) {
  browserLogs.length = 0
  })
 
+ test('invalidate', async () => {
+ browserLogs.length = 0
+ const el = await page.$('.invalidation')
+
+ editFile('invalidation/child.js', (code) =>
+ code.replace('child', 'child updated')
+ )
+ await untilUpdated(() => el.textContent(), 'child updated')
+ expect(browserLogs).toMatchObject([
+ '>>> vite:beforeUpdate -- update',
+ '>>> vite:invalidate -- /invalidation/child.js',
+ '[vite] hot updated: /invalidation/child.js',
+ '>>> vite:beforeUpdate -- update',
+ '(invalidation) parent is executing',
+ '[vite] hot updated: /invalidation/parent.js'
+ ])
+ browserLogs.length = 0
+ })
+
  test('plugin hmr handler + custom event', async () => {
  const el = await page.$('.custom')
  editFile('customFile.js', (code) => code.replace('custom', 'edited'))

playground/hmr/hmr.ts

@@ -2,6 +2,7 @@
 import { virtual } from 'virtual:file'
 import { foo as depFoo, nestedFoo } from './hmrDep'
 import './importing-updated'
+import './invalidation/parent'
 
 export const foo = 1
 text('.app', foo)
@@ -88,6 +89,10 @@ if (import.meta.hot) {
  console.log(`>>> vite:error -- ${event.type}`)
  })
 
+ import.meta.hot.on('vite:invalidate', ({ path }) => {
+ console.log(`>>> vite:invalidate -- ${path}`)
+ })
+
  import.meta.hot.on('custom:foo', ({ msg }) => {
  text('.custom', msg)
  })

playground/hmr/index.html

@@ -20,6 +20,7 @@
 <div class="nested"></div>
 <div class="custom"></div>
 <div class="virtual"></div>
+<div class="invalidation"></div>
 <div class="custom-communication"></div>
 <div class="css-prev"></div>
 <div class="css-post"></div>

playground/hmr/invalidation/child.js

@@ -0,0 +1,9 @@
+if (import.meta.hot) {
+ // Need to accept, to register a callback for HMR
+ import.meta.hot.accept(() => {
+ // Trigger HMR in importers
+ import.meta.hot.invalidate()
+ })
+}
+
+export const value = 'child'

playground/hmr/invalidation/parent.js

@@ -0,0 +1,9 @@
+import { value } from './child'
+
+if (import.meta.hot) {
+ import.meta.hot.accept()
+}
+
+console.log('(invalidation) parent is executing')
+
+document.querySelector('.invalidation').innerHTML = value