BrowserSync Webpack Plugin (v3 fork)

0.1.1 verified Sat Apr 25 auth: no javascript

A Webpack plugin that integrates BrowserSync for live reload and dev server proxy. This fork (v0.1.1) adds support for BrowserSync v3 (peer dep ^2 || ^3) while maintaining compatibility with Webpack 1–5. It can serve files directly or proxy Webpack Dev Server. BrowserSync starts only in watch mode. Minimal configuration: pass BrowserSync options as first argument and optional plugin options (reload, injectCss, name, callback) as second. Releases are infrequent.

Common errors

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

cause Package not installed.

fix

Run npm install --save-dev browser-sync-webpack-plugin

error TypeError: BrowserSyncPlugin is not a constructor ↓

cause Incorrect import style (e.g., using ES6 default import default).

fix

Use const BrowserSyncPlugin = require('browser-sync-webpack-plugin');

error Error: The 'mode' option has not been set, webpack will fallback to 'production' for this value. ↓

cause Webpack v4+ requires mode to be set explicitly.

fix

Set mode: 'development' in webpack config.

error Error: connect ECONNREFUSED 127.0.0.1:3100 ↓

cause When using proxy option, Webpack Dev Server is not running on the expected port.

fix

Start Webpack Dev Server first on the port you proxy (e.g., port 3100).

Warnings

gotcha BrowserSync only starts when webpack runs with --watch or watch: true. ↓

fix Ensure webpack is in watch mode.

gotcha The plugin name in require is 'browser-sync-webpack-plugin', not 'browser-sync-v3-webpack-plugin'. The fork is published as the same npm package name. ↓

fix Use 'browser-sync-webpack-plugin' as the package name.

deprecated Support for Node.js versions < 4 was dropped in v2.0.0. ↓

fix Upgrade Node.js to v4+ or use v1.2.0.

gotcha When using the proxy option, ensure 'reload: false' is set in plugin options to avoid double reloads. ↓

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

gotcha The 'injectCss' plugin option only works when changed chunks are all CSS files; otherwise page reloads. ↓

fix Set injectCss: true only if you expect CSS-only changes.

Install

npm install browser-sync-v3-webpack-plugin

yarn add browser-sync-v3-webpack-plugin

pnpm add browser-sync-v3-webpack-plugin

Imports

BrowserSyncPlugin

wrong

import BrowsersyncPlugin from 'browser-sync-webpack-plugin';

correct

const BrowserSyncPlugin = require('browser-sync-webpack-plugin');

Package is CommonJS only; default import does not work. Use require or ESM default interop.

new BrowserSyncPlugin()
wrong
```
new BrowserSyncPlugin();
```
correct
```
new BrowserSyncPlugin({host: 'localhost', port: 3000, server: {baseDir: ['./']}})
```
Plugin requires at least an options object. If omitted, BrowserSync may fail to start.

PluginOptions

wrong

new BrowserSyncPlugin({proxy: 'http://localhost:8080', reload: false})

correct

const BrowserSyncPlugin = require('browser-sync-webpack-plugin');
new BrowserSyncPlugin({proxy: 'http://localhost:8080'}, {reload: false})

reload is a plugin option, not a BrowserSync option; must be in second argument object.

Quickstart

Basic setup: serves files from 'dist' directory with BrowserSync on localhost:3000 when webpack runs in watch mode.

const BrowserSyncPlugin = require('browser-sync-webpack-plugin');
const path = require('path');

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