BrowserSync Webpack Plugin

2.4.0 verified Sat Apr 25 auth: no javascript

Webpack plugin that integrates BrowserSync for live reloading and cross-device testing during development. Current stable version is 2.4.0, with support for Webpack 1–5 and BrowserSync 2–3. It is typically used when you want BrowserSync's UI and synchronized browsing alongside Webpack's watch mode, either serving directly or proxying Webpack Dev Server. The plugin requires Node >=4 and is published on npm. Key differentiator: it adds BrowserSync's multi-device sync, UI dashboard, and tunnel capabilities to Webpack builds without needing to run a separate process. Contributions welcome, MIT license.

Common errors

error Error: Cannot find module 'browser-sync' ↓

cause browser-sync is a peer dependency and not installed automatically.

fix

Run npm install --save-dev browser-sync

error TypeError: BrowserSyncPlugin is not a constructor ↓

cause Incorrect import (using named import instead of default).

fix

Use const BrowserSyncPlugin = require('browser-sync-webpack-plugin') or import BrowserSyncPlugin from 'browser-sync-webpack-plugin'

error Error: webpack.optimize.OccurrenceOrderPlugin is not a plugin ↓

cause Using old plugin options with Webpack 4+.

fix

Remove webpack.optimize.OccurrenceOrderPlugin and use default optimization in webpack.config.js.

error ReferenceError: window is not defined ↓

cause Running BrowserSync inside Node environment (not relevant to plugin directly).

fix

Ensure you are not accidentally running browser-sync on server-side without proper configuration.

Warnings

deprecated Plugin will not automatically inject CSS changes unless `injectCss: true` option is set. Default behavior is full page reload. ↓

fix Set `injectCss: true` in plugin options to enable CSS injection without reload.

breaking Node v3 and lower support dropped in version 2.0.0. ↓

fix Use Node >=4. For older Node, use version 1.2.0.

gotcha BrowserSync only starts when Webpack runs in watch mode (`webpack --watch`). Build once without watch will not start BrowserSync. ↓

fix Ensure you run webpack with --watch flag.

gotcha When using with Webpack Dev Server, you must set `reload: false` to prevent double reloading. ↓

fix Pass `{ reload: false }` as second argument to BrowserSyncPlugin constructor.

gotcha The plugin expects BrowserSync v2 or v3. Make sure you have compatible version installed. ↓

fix Install `browser-sync` as a devDependency with version 2.x or 3.x.

Install

npm install browser-sync-webpack-plugin

yarn add browser-sync-webpack-plugin

pnpm add browser-sync-webpack-plugin

Imports

BrowserSyncPlugin
wrong
```
import BrowserSyncPlugin from 'browser-sync-webpack-plugin'
```
correct
```
const BrowserSyncPlugin = require('browser-sync-webpack-plugin')
```
CommonJS is the traditional pattern; ESM may not work depending on Node module resolution. Use require() for compatibility.

Default export (as plugin)

wrong

import { BrowserSyncPlugin } from 'browser-sync-webpack-plugin'

correct

import BrowserSyncPlugin from 'browser-sync-webpack-plugin'

The package exports a single constructor as default. Named import will be undefined.

TypeScript type (if needed)
wrong
```
import { BrowserSyncPlugin } from 'browser-sync-webpack-plugin'
```
correct
```
import BrowserSyncPlugin from 'browser-sync-webpack-plugin'
```
The package does not ship TypeScript definitions. If using TS, you may need to declare the module or add @types/browser-sync-webpack-plugin if available.

Quickstart

Shows basic usage of BrowserSyncPlugin with Webpack watch mode; starts a local server serving 'dist' directory on port 3000.

// webpack.config.js
const BrowserSyncPlugin = require('browser-sync-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: { path: __dirname + '/dist', filename: 'bundle.js' },
  plugins: [
    new BrowserSyncPlugin({
      host: 'localhost',
      port: 3000,
      server: { baseDir: ['dist'] }
    })
  ]
};