Registry /
web-framework / browsersync-webpack-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BrowserSyncPlugin
✓ import BrowserSyncPlugin from 'browsersync-webpack-plugin';
// or
const BrowserSyncPlugin = require('browsersync-webpack-plugin');
✗ import { BrowserSyncPlugin } from 'browsersync-webpack-plugin';
The plugin exports a default class, so use a default import or CommonJS require. Named imports will fail.
plugin options (BrowserSync options)
✓ new BrowserSyncPlugin({
host: 'localhost',
port: 3000,
server: { baseDir: ['public'] }
});
✗ new BrowserSyncPlugin('localhost', 3000, { server: { baseDir: ['public'] } });
The first argument to the constructor is an object containing standard BrowserSync options. Ensure it's a single object literal.
plugin options (Webpack Dev Server proxy)
✓ new BrowserSyncPlugin(
{ proxy: 'http://localhost:8080/' }, // BrowserSync options
{ reload: false } // Plugin specific options
);
✗ new BrowserSyncPlugin({ proxy: 'http://localhost:8080/', reload: false });
When proxying `webpack-dev-server`, BrowserSync options are the first argument, and `reload: false` (to let Webpack handle HMR) is passed in a *second* options object.
This `webpack.config.js` demonstrates how to integrate `browsersync-webpack-plugin` with `webpack-dev-middleware` and `webpack-hot-middleware` using a proxy setup.
const path = require('path');
const webpack = require('webpack');
const BrowserSyncPlugin = require('browsersync-webpack-plugin');
const webpackDevMiddleware = require('webpack-dev-middleware');
const webpackHotMiddleware = require('webpack-hot-middleware');
module.exports = {
mode: 'development',
entry: [
'webpack-hot-middleware/client?reload=true', // HMR client
'./src/index.js'
],
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js',
publicPath: '/dist/' // Crucial for webpack-dev-middleware
},
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: ['babel-loader']
}
]
},
plugins: [
new webpack.HotModuleReplacementPlugin(),
new webpack.NoEmitOnErrorsPlugin(), // Good practice with HMR
new BrowserSyncPlugin(
// BrowserSync options
{
host: 'localhost',
port: 3000,
proxy: 'http://localhost:8080/', // Proxy Webpack Dev Server
open: false // Prevent BrowserSync from opening a new browser tab automatically
},
// plugin options
{ reload: false } // Let Webpack Dev Server handle reloads
)
],
devServer: {
port: 8080, // Webpack Dev Server port
hot: true,
static: { // Or `contentBase` for Webpack 4 and earlier
directory: path.join(__dirname, 'public'),
},
// This devServer config might be ignored when running via custom server and middleware
// The middleware approach below takes precedence
}
};
// To run this setup, you typically need a custom Node.js server (e.g., Express).
// A simplified `server.js` for illustration:
/*
const express = require('express');
const webpack = require('webpack');
const webpackConfig = require('./webpack.config.js');
const compiler = webpack(webpackConfig);
const app = express();
app.use(webpackDevMiddleware(compiler, {
publicPath: webpackConfig.output.publicPath,
stats: { colors: true }
}));
app.use(webpackHotMiddleware(compiler));
// Serve static assets from 'public' if not proxied
app.use(express.static(path.join(__dirname, 'public')));
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
console.log(`Webpack Dev Server listening on port ${PORT}`);
});
*/
Debug
Known issues
breakingThe package `browsersync-webpack-plugin` is abandoned and has not been updated since April 2018. It is highly unlikely to be compatible with Webpack 5+ due to significant internal changes in Webpack's plugin API and Node.js polyfills. Using it with modern Webpack versions will likely lead to build failures or unexpected behavior.fixMigrate to a maintained alternative like `webpack-dev-server` with `browser-sync` used as a proxy manually configured, or find a more recent, actively maintained BrowserSync Webpack integration plugin if available. For Webpack 5+, `webpack-dev-server` handles HMR directly and is often sufficient.
affects: >=1.0.0 (Webpack versions)
gotchaThis plugin requires `browser-sync` as a peer dependency, but it specifies an old version range (`^2.18.8`). Newer versions of `browser-sync` (e.g., v3+) may introduce breaking changes or different API behaviors that are not accounted for by this abandoned plugin, leading to runtime errors or unexpected behavior.fixEnsure you install a compatible `browser-sync` version (e.g., `npm install browser-sync@^2.18.8`). Be aware that pinning to an old version might introduce security vulnerabilities or incompatibilities with your Node.js runtime.
affects: >=0.6.0 (browsersync-webpack-plugin)
deprecatedThe plugin's approach of integrating `webpack-dev-middleware` and `webpack-hot-middleware` directly into a BrowserSync instance via a separate plugin is largely superseded by modern `webpack-dev-server` capabilities, which include built-in HMR since v4.0.0.fixFor new projects, prefer using `webpack-dev-server` directly for development, which offers robust HMR and live reloading. If BrowserSync features (like UI, external device sync, or proxying to multiple backends) are essential, configure `browser-sync` to proxy the `webpack-dev-server` output manually.
affects: >=0.6.0
Errors
Common errors & fixes
TypeError: BrowserSyncPlugin is not a constructor
Attempting to use `import { BrowserSyncPlugin } from 'browsersync-webpack-plugin'` instead of a default import or CommonJS require for the class.
fixChange the import statement to `import BrowserSyncPlugin from 'browsersync-webpack-plugin';` for ES Modules or `const BrowserSyncPlugin = require('browsersync-webpack-plugin');` for CommonJS. Error: Cannot find module 'browser-sync'
The `browser-sync` package is a peer dependency and was not installed alongside `browsersync-webpack-plugin`.
fixInstall the peer dependency: `npm install browser-sync` or `yarn add browser-sync`. Check `package.json` for the expected version range.
BrowserSync not starting or HMR/live reload not working in browser
Incorrect configuration of `publicPath` in Webpack output, `webpack-dev-middleware` or `webpack-hot-middleware` not properly integrated, or BrowserSync options (like `proxy` or `server.baseDir`) are misconfigured.
fixEnsure `output.publicPath` in `webpack.config.js` matches the path where your bundled assets are expected to be served. Verify `webpackDevMiddleware` is configured with the correct `publicPath`. When proxying, ensure BrowserSync's `proxy` option points to the correct `webpack-dev-server` address and port. If using a static server, `server.baseDir` must point to the directory containing your static files.
Audit
Dependencies
browser-syncrequiredRequired peer dependency for BrowserSync functionality. The plugin wraps an instance of BrowserSync.