or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

file-watching.mdindex.mdinstance-management.mdnotifications-ui.mdplugins.mdserver-proxy.mdsynchronization.md
tile.json

tessl/npm-browser-sync

Live CSS Reload & Browser Syncing development tool for synchronized browsing across multiple devices and browsers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/browser-sync@3.0.x

To install, run

npx @tessl/cli install tessl/npm-browser-sync@3.0.0

index.mddocs/

Browser-sync

Browser-sync is a development tool that enables synchronized browsing across multiple devices and browsers during web development. It provides live CSS reload capabilities, browser synchronization for form inputs, page scrolling, and clicks, along with a built-in server for serving static files and proxying existing servers.

Package Information

  • Package Name: browser-sync
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install browser-sync

Core Imports

const browserSync = require('browser-sync');

For ES modules:

import browserSync from 'browser-sync';

Basic Usage

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

// Start a server
browserSync.init({
    server: "./app",
    files: ["./app/**/*.css", "./app/**/*.html"]
});

// Or proxy existing server
browserSync.init({
    proxy: "localhost:3000",
    files: ["./css/**/*.css", "./templates/**/*.html"]
});

Architecture

Browser-sync is built around several key components:

  • Core Instance Management: Singleton pattern with named instance support for managing multiple servers
  • Server Mode: Built-in static file server with middleware support and routing capabilities
  • Proxy Mode: HTTP/HTTPS proxy server with websocket support for proxying existing applications
  • File Watching: Chokidar-based file monitoring with glob pattern support and debounced reload events
  • Socket Communication: Socket.IO-based real-time communication between server and connected browsers
  • Synchronization Engine: Cross-device interaction mirroring for clicks, scrolls, form inputs, and navigation
  • CLI Interface: Command-line tool with extensive options for configuration and one-off tasks

Capabilities

Instance Management

Core functionality for creating, managing, and controlling browser-sync instances. Essential for all browser-sync usage patterns.

/**
 * Initialize a browser-sync instance with configuration
 */
function browserSync(config?: BrowserSyncConfig, callback?: Function): BrowserSyncInstance;

/**
 * Create a named browser-sync instance
 */
browserSync.create(name?: string): BrowserSyncInstance;

/**
 * Get an existing instance by name
 */
browserSync.get(name: string): BrowserSyncInstance;

/**
 * Check if an instance exists
 */
browserSync.has(name: string): boolean;

Instance Management

Server and Proxy Configuration

Configuration options for running browser-sync as either a static file server or as a proxy to existing servers. Supports middleware, routing, and HTTPS.

interface ServerConfig {
    baseDir: string | string[];
    index?: string;
    directory?: boolean;
    routes?: { [route: string]: string };
    middleware?: Function | Function[];
}

interface ProxyConfig {
    target: string;
    ws?: boolean;
    middleware?: Function | Function[];
}

Server and Proxy

File Watching and Reloading

File monitoring system with CSS injection capabilities and browser reload functionality. Supports glob patterns, ignore patterns, and custom reload strategies.

/**
 * Reload browsers with optional file specification
 */
reload(files?: string | string[] | ReloadOptions): void;

/**
 * Transform stream for build tool integration
 */
stream(options?: StreamOptions): NodeJS.ReadWriteStream;

/**
 * Watch files for changes
 */
watch(patterns: string, options?: WatchOptions, callback?: Function): void;

File Watching

Browser Synchronization

Cross-device interaction synchronization including clicks, scrolls, form inputs, and navigation. Configurable ghostMode settings and element-specific scroll synchronization.

interface GhostModeConfig {
    clicks?: boolean;
    scroll?: boolean;
    location?: boolean;
    forms?: {
        submit?: boolean;
        inputs?: boolean;
        toggles?: boolean;
    };
}

Browser Synchronization

Notifications and UI

Browser notification system and web-based control UI for managing connected devices and controlling synchronization settings.

/**
 * Display notification in connected browsers
 */
notify(message: string | HTML, timeout?: number): void;

interface UIConfig {
    port?: number;
}

Notifications and UI

Plugin System

Extensible plugin architecture for adding custom functionality and integrating with build tools and other development workflows.

/**
 * Register a plugin
 */
use(name: string, plugin: BrowserSyncPlugin, callback?: Function): void;

interface BrowserSyncPlugin {
    plugin(options: any, bs: BrowserSyncInstance): any;
}

Plugin System

Types

Core Types

interface BrowserSyncInstance {
    init(config?: BrowserSyncConfig, callback?: Function): BrowserSyncInstance;
    reload(files?: string | string[] | ReloadOptions): void;
    stream(options?: StreamOptions): NodeJS.ReadWriteStream;
    notify(message: string, timeout?: number): void;
    exit(): void;
    watch(patterns: string, options?: any, callback?: Function): void;
    pause(): void;
    resume(): void;
    use(name: string, plugin: any, callback?: Function): void;
    getOption(key: string): any;
    emitter: EventEmitter;
    active: boolean;
    paused: boolean;
    sockets: any;
}

interface BrowserSyncConfig {
    server?: string | string[] | ServerConfig | boolean;
    proxy?: string | ProxyConfig | boolean;
    files?: string | string[] | FilesConfig[] | boolean;
    port?: number;
    host?: string;
    https?: boolean | HttpsConfig;
    open?: boolean | string;
    browser?: string | string[];
    ghostMode?: GhostModeConfig | boolean;
    logLevel?: "silent" | "info" | "debug" | "warn";
    ui?: UIConfig | boolean;
    // ... additional configuration options
}

File and Stream Types

interface FilesConfig {
    match: string | string[];
    fn?: Function;
    options?: any;
}

interface ReloadOptions {
    stream?: boolean;
    once?: boolean;
    match?: string | string[];
}

interface StreamOptions {
    once?: boolean;
    match?: string | string[];
}

interface WatchOptions {
    ignoreInitial?: boolean;
    ignored?: string | RegExp | string[];
    // ... additional chokidar options
}