BrowserSync Webpack Plugin
raw JSON →The `browsersync-webpack-plugin` package provides a bridge to integrate BrowserSync with Webpack projects, particularly useful for development workflows. It aims to simplify the setup of live reloading and synchronized browser testing by combining BrowserSync's features with Webpack's build process, often alongside `webpack-dev-middleware` and `webpack-hot-middleware`. The provided version, `0.6.0`, was published in April 2018. The package itself appears to be largely unmaintained or abandoned, with the last code commit and NPM publish occurring approximately six years ago. This makes it unsuitable for modern Webpack 5+ setups and potentially incompatible with newer Node.js versions or recent BrowserSync releases. Users should be aware of its inactive status and consider alternatives for contemporary projects. It differentiates itself by offering a direct plugin approach to embed BrowserSync into Webpack's lifecycle, rather than configuring BrowserSync manually to proxy a `webpack-dev-server` instance.
Common errors
error TypeError: BrowserSyncPlugin is not a constructor ↓
import BrowserSyncPlugin from 'browsersync-webpack-plugin'; for ES Modules or const BrowserSyncPlugin = require('browsersync-webpack-plugin'); for CommonJS. error Error: Cannot find module 'browser-sync' ↓
npm install browser-sync or yarn add browser-sync. Check package.json for the expected version range. error BrowserSync not starting or HMR/live reload not working in browser ↓
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. Warnings
breaking The 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. ↓
gotcha This 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. ↓
deprecated The 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. ↓
Install
npm install browsersync-webpack-plugin yarn add browsersync-webpack-plugin pnpm add browsersync-webpack-plugin Imports
- BrowserSyncPlugin wrong
import { BrowserSyncPlugin } from 'browsersync-webpack-plugin';correctimport BrowserSyncPlugin from 'browsersync-webpack-plugin'; // or const BrowserSyncPlugin = require('browsersync-webpack-plugin'); - plugin options (BrowserSync options) wrong
new BrowserSyncPlugin('localhost', 3000, { server: { baseDir: ['public'] } });correctnew BrowserSyncPlugin({ host: 'localhost', port: 3000, server: { baseDir: ['public'] } }); - plugin options (Webpack Dev Server proxy) wrong
new BrowserSyncPlugin({ proxy: 'http://localhost:8080/', reload: false });correctnew BrowserSyncPlugin( { proxy: 'http://localhost:8080/' }, // BrowserSync options { reload: false } // Plugin specific options );
Quickstart
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}`);
});
*/