vite-plugin-browser-sync

7.0.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that integrates BrowserSync into your Vite development workflow. Current stable version is v7.0.0, supporting Vite 7 and 8 with Node 20+. It provides zero-config setup for common use cases, supports BrowserSync proxy and snippet modes, and can run on dev, preview, and build --watch. Key differentiators: seamless integration with Vite's ecosystem, automatic syncing of Vite server options, and full BrowserSync features. Release cadence follows major Vite versions with breaking changes. Ships TypeScript types.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-browser-sync/dist/index.js from /path/to/vite.config.js not supported. ↓

cause The package is ESM-only since v6.0.0, but your vite.config.js uses CommonJS require().

fix

Convert your config to ESM (use .mjs or add 'type': 'module' in package.json) or use dynamic import: const VitePluginBrowserSync = (await import('vite-plugin-browser-sync')).default

error TypeError: VitePluginBrowserSync is not a function ↓

cause Using named import { VitePluginBrowserSync } instead of default import.

fix

Change import to: import VitePluginBrowserSync from 'vite-plugin-browser-sync'

error Error: The plugin requires Vite 7 or 8. Current Vite version is X.Y.Z. ↓

cause Running an incompatible version of Vite (e.g., Vite 6).

fix

Upgrade Vite to ^7.0.0 or ^8.0.0, or downgrade the plugin to version 5.0 (supports Vite 6-7).

Warnings

breaking v7.0.0 drops support for Vite 6 and Node 18. Requires Vite 7+ and Node 20+. ↓

fix Upgrade to Vite 7+ and Node 20+. If unable, use version 5.0 of the plugin.

breaking v6.0.0 drops CJS support. The package is now ESM-only. ↓

fix Use ESM imports; switch to dynamic import if CJS is required: const VitePluginBrowserSync = (await import('vite-plugin-browser-sync')).default

deprecated The 'bs' top-level option (used in v2.x) is deprecated since v3.0.0. ↓

fix Wrap BrowserSync options inside a 'dev' object, e.g., { dev: { bs: {...} } }.

gotcha In 'buildWatch' mode, if using 'proxy' default, you must explicitly set the 'bs' object with a proxy target. ↓

fix Configure 'buildWatch.bs.proxy' to point to your server, e.g., proxy: 'http://localhost:3000'

gotcha For Astro projects, the plugin does not work in 'preview' mode due to Astro's overrides. ↓

fix Use only 'dev' mode with Astro. Alternatively, disable preview mode: { preview: { enable: false } }

Install

npm install vite-plugin-browser-sync

yarn add vite-plugin-browser-sync

pnpm add vite-plugin-browser-sync

Imports

VitePluginBrowserSync

wrong

const VitePluginBrowserSync = require('vite-plugin-browser-sync')

correct

import VitePluginBrowserSync from 'vite-plugin-browser-sync'

ESM-only since v6.0.0 - CommonJS require() will fail.

VitePluginBrowserSync

wrong

import { VitePluginBrowserSync } from 'vite-plugin-browser-sync'

correct

import VitePluginBrowserSync from 'vite-plugin-browser-sync'

Default export, not named.

VitePluginBrowserSync
```
const VitePluginBrowserSync = (await import('vite-plugin-browser-sync')).default
```
Dynamic import in CJS or ESM contexts to avoid top-level import issues.

Quickstart

Shows basic usage with custom BrowserSync options for the dev server, including disabling the notify banner and setting the UI port.

import { defineConfig } from 'vite';
import VitePluginBrowserSync from 'vite-plugin-browser-sync';

export default defineConfig({
  plugins: [
    VitePluginBrowserSync({
      dev: {
        bs: {
          ui: { port: 8080 },
          notify: false
        }
      }
    })
  ]
});