npm browser-sync Package - Complete Setup and Usage Guide

Browser-sync is a powerful development tool that provides live reloading, CSS injection, and synchronization across multiple devices. It’s essential for modern web development workflows.

This guide covers installation, configuration, and advanced usage of browser-sync.

Introduction to browser-sync

Browser-sync automatically refreshes your browser when files change, injects CSS without page reload, and synchronizes scrolling and clicks across multiple devices.

Key Features:

• Live reload on file changes
• CSS injection (no page reload)
• Multi-device synchronization
• Network access for mobile testing
• Proxy mode for existing servers

Use Cases:

• Local development
• Multi-device testing
• Team collaboration
• Responsive design testing
• Live CSS editing

Installation

Global Installation

npm install -g browser-sync

Local Installation

npm install --save-dev browser-sync

Verify Installation

browser-sync --version

Basic Usage

Start Server

Serve static files:

browser-sync start --server

With directory:

browser-sync start --server --files "css/*.css"

Watch Files

browser-sync start --server --files "**/*.css, **/*.html, **/*.js"

Proxy Mode

Proxy existing server:

browser-sync start --proxy "localhost:8080" --files "**/*.css"

Configuration Options

Configuration File

Create bs-config.js:

module.exports = {
    server: {
        baseDir: "./dist"
    },
    files: ["dist/**/*.css", "dist/**/*.html"],
    port: 3000,
    open: false,
    notify: false
};

Run with config:

browser-sync start --config bs-config.js

Common Options

{
    server: "./dist",           // Base directory
    files: ["**/*.css"],        // Files to watch
    port: 3000,                 // Port number
    open: true,                  // Open browser
    notify: true,                // Show notifications
    reloadOnRestart: true,      // Reload on restart
    ui: { port: 3001 }          // UI port
}

Live Reloading

Automatic Reload

browser-sync start --server --files "**/*.html, **/*.css, **/*.js"

Any changes to watched files trigger automatic browser reload.

CSS Injection

CSS files are injected without full page reload:

browser-sync start --server --files "**/*.css"

Only CSS updates, page doesn’t reload.

Multi-Device Synchronization

Access from Network

Browser-sync provides network URL:

Local:    http://localhost:3000
External: http://192.168.1.100:3000

Sync Features

• Scroll synchronization
• Click synchronization
• Form input synchronization
• URL synchronization

All devices see the same interactions in real-time.

Integration with Build Tools

Gulp Integration

const gulp = require('gulp');
const browserSync = require('browser-sync').create();

gulp.task('serve', function() {
    browserSync.init({
        server: './dist'
    });
    
    gulp.watch('src/**/*.html').on('change', browserSync.reload);
});

Webpack Integration

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

module.exports = {
    plugins: [
        new BrowserSyncPlugin({
            host: 'localhost',
            port: 3000,
            server: { baseDir: ['dist'] }
        })
    ]
};

npm Scripts

package.json:

{
  "scripts": {
    "dev": "browser-sync start --server --files '**/*.css, **/*.html'"
  }
}

Run:

npm run dev

Advanced Features

Custom Middleware

module.exports = {
    server: {
        baseDir: "./",
        middleware: [
            function(req, res, next) {
                // Custom middleware
                next();
            }
        ]
    }
};

HTTPS Support

browser-sync start --server --https

Custom Ports

browser-sync start --server --port 4000 --ui-port 4001

Best Practices

1. Watch specific files - Don’t watch node_modules
2. Use proxy mode - For existing development servers
3. Disable notifications - In production-like setups
4. Configure ports - Avoid conflicts
5. Use config files - For complex setups

Conclusion

Browser-sync provides:

• Live reloading for faster development
• CSS injection without page reload
• Multi-device sync for testing
• Easy integration with build tools

Key Points:

• Install globally or locally
• Watch files for changes
• Use proxy mode for existing servers
• Configure for your workflow
• Integrate with build tools

Browser-sync significantly improves development workflow and testing efficiency.