BrowserSync Webpack Plugin

raw JSON →
0.6.0 verified Thu Apr 23 auth: no javascript abandoned

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.

error TypeError: BrowserSyncPlugin is not a constructor
cause Attempting to use `import { BrowserSyncPlugin } from 'browsersync-webpack-plugin'` instead of a default import or CommonJS require for the class.
fix
Change the import statement to 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'
cause The `browser-sync` package is a peer dependency and was not installed alongside `browsersync-webpack-plugin`.
fix
Install the peer dependency: 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
cause 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.
fix
Ensure 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.
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.
fix Migrate 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.
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.
fix Ensure 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.
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.
fix For 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.
npm install browsersync-webpack-plugin
yarn add browsersync-webpack-plugin
pnpm add browsersync-webpack-plugin

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}`);
});
*/