BrowserSync Webpack Plugin

BrowserSync Webpack Plugin provides seamless integration between BrowserSync and Webpack, enabling live reloading and synchronization features during development. The plugin automatically starts BrowserSync when Webpack runs in watch mode and supports both static file serving and proxying through Webpack Dev Server.

Package Information

• Package Name: browser-sync-webpack-plugin
• Package Type: npm
• Language: JavaScript
• Installation: npm install --save-dev browser-sync-webpack-plugin

Core Imports

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

For ES modules:

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

Basic Usage

Static File Serving

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

module.exports = {
  // webpack config
  plugins: [
    new BrowserSyncPlugin({
      // BrowserSync options - serve static files
      host: 'localhost',
      port: 3000,
      server: { baseDir: ['public'] }
    })
  ]
};

Advanced Usage with Webpack Dev Server

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

module.exports = {
  // webpack config
  plugins: [
    new BrowserSyncPlugin(
      // BrowserSync options - proxy through webpack-dev-server
      {
        host: 'localhost',
        port: 3000,
        proxy: 'http://localhost:3100/'
      },
      // Plugin options
      {
        reload: false,
        name: 'my-browsersync-instance',
        callback: (err, bs) => {
          if (err) console.error('BrowserSync error:', err);
          console.log('BrowserSync started');
        }
      }
    )
  ]
};

Architecture

BrowserSync Webpack Plugin is built around several key integration patterns:

• Webpack Hook System: Integrates with Webpack's plugin architecture through three key hooks (watch-run, compilation, done)
• Lazy Initialization: BrowserSync instance is only created and started after the first successful Webpack compilation in watch mode
• State Management: Maintains internal state tracking for Webpack watch mode and BrowserSync running status to coordinate behavior
• Dual Mode Operation: Supports both static file serving (development server replacement) and proxy mode (integration with webpack-dev-server)
• Instance Isolation: Creates named BrowserSync instances to prevent conflicts when multiple plugins are used

Capabilities

BrowserSyncPlugin Constructor

Creates a new BrowserSync webpack plugin instance with specified options.

/**
 * Creates a BrowserSync webpack plugin
 * @param {Object} browserSyncOptions - Options passed to BrowserSync.init()
 * @param {Object} [pluginOptions] - Plugin-specific configuration options
 */
function BrowserSyncPlugin(browserSyncOptions, pluginOptions)

Constructor Parameters

browserSyncOptions (Object, optional)

• Configuration options passed directly to BrowserSync.init()
• Supports all BrowserSync options
• Common options include host, port, server, proxy, notify, open
• Default: {}

pluginOptions (Object, optional)

• Plugin-specific configuration options
• Default: {reload: true, name: 'bs-webpack-plugin', callback: undefined}

Plugin Options

/**
 * Plugin-specific configuration options
 * @typedef {Object} PluginOptions
 * @property {boolean} [reload=true] - Whether to trigger browser reload on webpack compilation completion
 * @property {string} [name='bs-webpack-plugin'] - BrowserSync instance name for identification
 * @property {function} [callback] - Callback function passed to BrowserSync.init()
 */

reload (boolean)

• Controls whether the browser reloads on webpack compilation completion
• Set to false when using with webpack-dev-server to avoid conflicting reloads
• Default: true

name (string)

• BrowserSync instance name for identification
• Useful when running multiple BrowserSync instances
• Default: 'bs-webpack-plugin'

callback (function)

• Callback function executed when BrowserSync initialization completes
• Receives error (if any) and BrowserSync instance as parameters
• Default: undefined

Plugin Methods

apply

Webpack plugin interface method that registers compilation hooks.

/**
 * Webpack plugin interface method
 * @param {Object} compiler - Webpack compiler instance
 */
apply(compiler)

This method is called automatically by Webpack and registers the following hooks:

• watch-run: Detects when Webpack enters watch mode
• compilation: Shows "Rebuilding..." notification during compilation
• done: Initializes BrowserSync or triggers reload after compilation

Error Handling

The plugin handles BrowserSync initialization errors through the optional callback function. If no callback is provided, errors are handled internally by BrowserSync.

new BrowserSyncPlugin(
  { /* browserSync options */ },
  {
    callback: (err, bs) => {
      if (err) {
        console.error('BrowserSync failed to start:', err);
      } else {
        console.log('BrowserSync is running at:', bs.getOption('urls'));
      }
    }
  }
);

Behavior Notes

• BrowserSync only starts when Webpack runs in watch mode (webpack --watch)
• The plugin creates a named BrowserSync instance to avoid conflicts
• Initialization is lazy - BrowserSync starts after the first successful compilation
• Supports both serving static files directly and proxying webpack-dev-server
• When reload: false, the plugin relies on webpack-dev-server's hot module replacement instead of BrowserSync reloading

Dependencies

• Peer Dependencies: browser-sync@^2, webpack@^1 || ^2 || ^3
• Runtime Dependencies: lodash@^4 (used internally for option merging)