The `import.meta.hot` API: Complete Guide

if (import.meta.hot) {
  // This code only runs in dev mode
  // It will be tree-shaken away at build time
}

// src/counter.ts
let count = 0

export function getCount() {
  return count
}
export function increment() {
  count++
}

// Declare: when this module itself updates, call this callback
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    // newModule is the freshly-executed new module
    // Migrate state from the old module to the new one here
    console.log("counter module hot updated")
  })
}

// src/App.tsx
import { getCount } from "./counter"

if (import.meta.hot) {
  // Accept updates from the counter module
  import.meta.hot.accept("./counter", (newCounter) => {
    // After counter updates, re-initialize with the new counter
    console.log("counter updated, new value:", newCounter?.getCount())
  })
}

if (import.meta.hot) {
  import.meta.hot.accept(["./moduleA", "./moduleB"], ([newA, newB]) => {
    // Triggered when either one updates
    console.log("A or B updated")
  })
}

if (import.meta.hot) {
  import.meta.hot.accept()
  // No arguments: accept self-updates but run no callback
  // Suitable for modules that only export pure functions — no explicit state migration needed
}

Button.tsx changes
    │
    ▼ Check: does Button.tsx have import.meta.hot.accept()?
    │
    ├── Yes → stop here, HMR-update Button.tsx
    │
    └── No → keep going up to the importer
          │
          App.tsx: has accept("./Button", ...)?
          ├── Yes → stop at App.tsx
          └── No → keep going up...
                main.tsx: No → full page reload!

// A module with side effects
let timer: ReturnType<typeof setInterval>

export function startTimer() {
  timer = setInterval(() => console.log("tick"), 1000)
}

if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    // The old module is about to be destroyed: clean up side effects
    clearInterval(timer)
    console.log("timer cleaned up")
  })

  import.meta.hot.accept()
}

1. File changes
2. dispose callback runs (cleans up old module's side effects)
3. New module code executes (re-initializes)
4. accept callback runs (state migration)

if (import.meta.hot) {
  import.meta.hot.accept(() => {
    // The module updated, but some global state cannot be reset
    if (someGlobalState.isCorrupted()) {
      // Declare that hot update is not possible, trigger a full page reload
      import.meta.hot!.invalidate()
    }
  })
}

// Suppose you want to preserve some state across hot updates
if (import.meta.hot) {
  // The old value from before the hot update lives in data
  const previousCount = import.meta.hot.data.count ?? 0

  let count = previousCount // initialize with the old value

  export function getCount() {
    return count
  }

  import.meta.hot.accept(() => {
    // Store the current value into data when hot updating
    import.meta.hot!.data.count = count
  })
}

// Your code:
export function Button({ label }) {
  return <button>{label}</button>
}

// Plugin auto-injected (simplified):
if (import.meta.hot) {
  const prevRefreshReg = window.$RefreshReg$
  window.$RefreshReg$ = (type, id) => {
    RefreshRuntime.register(type, module.id + " " + id)
  }
  import.meta.hot.accept()
  // Register the React component for Fast Refresh
}

// Implement a module with side effects that correctly handles HMR:
// 1. On module load, register a keyboard event listener
// 2. On hot update: remove the old listener first, then register a new one
// 3. Use data to preserve the current key-press count so it survives hot updates

export function setupKeyListener(callback: (key: string) => void) {
  const handler = (e: KeyboardEvent) => callback(e.key)
  document.addEventListener("keydown", handler)
  return () => document.removeEventListener("keydown", handler)
}

// TODO: add HMR support
// Requirements:
// - Remove the old listener on hot update
// - Re-register a new listener after hot update
// - Use data to preserve the key-press count (no loss across hot updates)
if (import.meta.hot) {
  // TODO
}