vite-plugin-crx-hot-reload

1.0.4 verified Mon Apr 27 auth: no javascript

A Vite plugin for hot-reloading Chrome extensions during development. Current stable version is 1.0.4, released on an as-needed cadence. It establishes a WebSocket connection to notify the extension to reload when file changes are detected, similar to HMR for web apps. Unlike generic HMR plugins, it specifically handles extension manifests and content scripts. Requires setting `build.emptyOutDir` to `false` and providing a manifest file path. Lightweight alternative to manual extension reloading or using browser-specific tools.

Common errors

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

cause Package not installed or import path incorrect.

fix

Run pnpm add -D vite-plugin-crx-hot-reload and ensure import is as shown.

error Uncaught (in promise) WebSocket connection to 'ws://localhost:8181/' failed ↓

cause Port conflict or WebSocket server not started due to missing plugin or config.

fix

Verify plugin is added to Vite config and port is available. Try changing port via options.

error Require is not defined in ES module scope ↓

cause Using CommonJS require() instead of ESM import.

fix

Replace const crxHotReload = require(...) with import crxHotReload from 'vite-plugin-crx-hot-reload'.

Warnings

gotcha Must set `build.emptyOutDir` to `false` in vite config, otherwise the build output will be cleared on each change, breaking the extension. ↓

fix Add `build: { emptyOutDir: false }` to your Vite config.

gotcha After starting the project, content_scripts changes may not auto-refresh; a manual page refresh might be needed initially. ↓

fix Refresh the extension page manually after the first change to content_scripts.

gotcha The plugin uses WebSocket default port 8181; conflicts with other services may cause connection failures. ↓

fix Change the port using `crxHotReload({ port: 8182, input: '...' })`.

gotcha Only works with Vite-based extension projects; not compatible with webpack or other bundlers. ↓

fix Use Vite as your build tool.

Install

npm install vite-plugin-crx-hot-reload

yarn add vite-plugin-crx-hot-reload

pnpm add vite-plugin-crx-hot-reload

Imports

crxHotReload

wrong

const crxHotReload = require('vite-plugin-crx-hot-reload')

correct

import crxHotReload from 'vite-plugin-crx-hot-reload'

ESM-only; no CommonJS export

Plugin

wrong

import { Plugin } from 'vite-plugin-crx-hot-reload'

correct

import type { Plugin } from 'vite'

Type is imported from Vite, not this plugin

ViteConfig

wrong

import { defineConfig, UserConfig } from 'vite-plugin-crx-hot-reload'

correct

import { defineConfig, type UserConfig } from 'vite'

Configuration types are from Vite

Quickstart

Basic setup: import the plugin, provide manifest path, and disable emptyOutDir for development.

import crxHotReload from 'vite-plugin-crx-hot-reload';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [crxHotReload({ input: './src/manifest.json' })],
  build: { emptyOutDir: false },
});