Hot Reload Chrome Extension - Vite Plugin

1.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables hot reload for Chrome extensions built on Manifest V3. Version 1.1.0, maintained via single author on GitHub. Releases are occasional. Key differentiator: simple setup with WebSocket-based reload for background scripts and optional side panel, using Vite's build watch mode. No HMR, only full reload on file changes. Requires NODE_ENV=development.

Common errors

error Error: Cannot find module 'hot-reload-extension-vite' ↓

cause Package not installed as dev dependency.

fix

npm install hot-reload-extension-vite -D

error TypeError: hotReloadExtension is not a function ↓

cause Using CommonJS require() instead of ESM import.

fix

Change require('hot-reload-extension-vite') to import hotReloadExtension from 'hot-reload-extension-vite' in a module context.

error Error: 'backgroundPath' is required ↓

cause Missing backgroundPath option in plugin configuration.

fix

Add backgroundPath pointing to your background script, e.g., backgroundPath: 'src/background.ts'.

error WebSocket connection to 'ws://localhost:8080/' failed ↓

cause Port 8080 already in use or WebSocket server not started (NODE_ENV not development).

fix

Set NODE_ENV=development and/or change port via HOT_RELOAD_EXTENSION_VITE_PORT env variable.

Warnings

breaking Plugin requires NODE_ENV=development to trigger reload. In production, plugin is no-op. ↓

fix Set NODE_ENV=development environment variable when running vite build --watch.

gotcha Plugin uses WebSocket on port 8080 by default. If another service uses that port, set HOT_RELOAD_EXTENSION_VITE_PORT environment variable. ↓

fix export HOT_RELOAD_EXTENSION_VITE_PORT=9090 Then run vite build --watch.

gotcha backgroundPath option is relative to project root, not src directory. Plugin expects a TypeScript file. ↓

fix Use full relative path from project root, e.g., 'src/background.ts'.

deprecated sidePanel options changed in v1.0.14: 'scriptPath' renamed to 'path', 'htmlPath' remains same. ↓

fix Update sidePanel config: use 'path' instead of 'scriptPath'.

Install

npm install hot-reload-extension-vite

yarn add hot-reload-extension-vite

pnpm add hot-reload-extension-vite

Imports

default

wrong

const hotReloadExtension = require('hot-reload-extension-vite')

correct

import hotReloadExtension from 'hot-reload-extension-vite'

ESM-only plugin; CJS require will fail because package is type: module and exports ESM.

SidePanelOptions

wrong

import { SidePanelOptions } from 'hot-reload-extension-vite'

correct

import type { SidePanelOptions } from 'hot-reload-extension-vite'

Type import only; runtime import will cause error because SidePanelOptions is a type, not a value.

HotReloadConfig

wrong

import { HotReloadConfig } from 'hot-reload-extension-vite'

correct

import type { HotReloadConfig } from 'hot-reload-extension-vite'

Similarly, use type import for config type.

Quickstart

Minimal Vite config for Chrome extension hot reload with background and side panel.

// vite.config.ts
import { defineConfig } from 'vite';
import hotReloadExtension from 'hot-reload-extension-vite';

export default defineConfig({
  plugins: [
    hotReloadExtension({
      log: true,
      backgroundPath: 'src/background.ts',
      sidePanel: {
        path: 'src/sidePanel.ts',
        htmlPath: 'public/sidePanel.html'
      }
    })
  ],
  build: {
    rollupOptions: {
      input: {
        background: 'src/background.ts',
        sidePanel: 'src/sidePanel.html'
      }
    }
  }
});

// Run build with watch mode:
// NODE_ENV=development npx vite build --watch