Browser-sync's core synchronization engine enables real-time mirroring of user interactions across multiple connected devices and browsers. This includes clicks, scrolls, form inputs, and navigation - essential for responsive design testing and cross-device development.
Control which user interactions are synchronized across connected browsers and devices.
/**
* Cross-device interaction mirroring settings
*/
ghostMode?: boolean | GhostModeConfig;
interface GhostModeConfig {
/** Synchronize click events (default: true) */
clicks?: boolean;
/** Synchronize scroll events (default: true) */
scroll?: boolean;
/** Synchronize location/navigation changes (default: true) */
location?: boolean;
/** Form interaction synchronization */
forms?: {
/** Synchronize form submissions (default: true) */
submit?: boolean;
/** Synchronize input field changes (default: true) */
inputs?: boolean;
/** Synchronize checkbox/radio toggles (default: true) */
toggles?: boolean;
};
}Usage Examples:
const browserSync = require('browser-sync');
// Enable all synchronization (default)
browserSync({
server: './app',
ghostMode: true
});
// Disable all synchronization
browserSync({
server: './app',
ghostMode: false
});
// Selective synchronization
browserSync({
server: './app',
ghostMode: {
clicks: true,
scroll: true,
location: false, // Don't sync navigation
forms: {
submit: false, // Don't sync form submissions
inputs: true,
toggles: true
}
}
});
// Debugging setup - only sync scrolling
browserSync({
server: './app',
ghostMode: {
clicks: false,
scroll: true,
location: false,
forms: false
}
});Advanced scroll synchronization with proportional positioning and element-specific synchronization.
/**
* Sync scroll position proportionally across devices (default: true)
*/
scrollProportionally?: boolean;
/**
* Throttle scroll events in milliseconds (default: 0)
*/
scrollThrottle?: number;
/**
* Method for restoring scroll position (default: "window.name")
*/
scrollRestoreTechnique?: "window.name" | "cookie";
/**
* CSS selectors for elements to sync scroll (default: [])
*/
scrollElements?: string[];
/**
* Bidirectional scroll sync element mapping (default: [])
*/
scrollElementMapping?: string[];Usage Examples:
const browserSync = require('browser-sync');
// Basic proportional scrolling
browserSync({
server: './app',
scrollProportionally: true,
scrollThrottle: 100 // Throttle for performance
});
// Element-specific scroll sync
browserSync({
server: './app',
scrollElements: [
'.sidebar',
'#main-content',
'.modal-body'
],
scrollElementMapping: [
'.left-panel',
'.right-panel'
]
});
// Custom scroll restore technique
browserSync({
server: './app',
scrollRestoreTechnique: 'cookie', // Use cookies instead of window.name
scrollThrottle: 50
});
// Disable proportional scrolling for pixel-perfect sync
browserSync({
server: './app',
scrollProportionally: false, // Sync exact pixel positions
scrollElements: ['.content']
});Detailed control over form input synchronization across connected browsers.
interface FormSyncConfig {
/** Synchronize form submissions */
submit?: boolean;
/** Synchronize text inputs, textareas, and select elements */
inputs?: boolean;
/** Synchronize checkboxes and radio buttons */
toggles?: boolean;
}Usage Examples:
const browserSync = require('browser-sync');
// Full form synchronization
browserSync({
server: './app',
ghostMode: {
forms: {
submit: true,
inputs: true,
toggles: true
}
}
});
// Input-only synchronization (no form submissions)
browserSync({
server: './app',
ghostMode: {
forms: {
submit: false, // Don't trigger actual form submissions
inputs: true, // Sync typing in real-time
toggles: true // Sync checkbox/radio changes
}
}
});
// Disable form sync for sensitive forms
browserSync({
server: './app',
ghostMode: {
clicks: true,
scroll: true,
forms: false // Disable all form synchronization
}
});Control click event synchronization with configurable behavior for different interaction types.
/**
* Click synchronization configuration
*/
interface ClickSyncConfig {
/** Enable/disable click synchronization */
clicks?: boolean;
}Usage Examples:
const browserSync = require('browser-sync');
// Standard click synchronization
browserSync({
server: './app',
ghostMode: {
clicks: true
}
});
// Disable clicks for presentation mode
browserSync({
server: './app',
ghostMode: {
clicks: false, // Prevent accidental navigation during demos
scroll: true,
forms: false
}
});Control synchronized navigation and URL changes across connected browsers.
/**
* Location/navigation synchronization
*/
interface LocationSyncConfig {
/** Synchronize navigation and URL changes */
location?: boolean;
}Usage Examples:
const browserSync = require('browser-sync');
// Full navigation sync
browserSync({
server: './app',
ghostMode: {
location: true // Navigate all browsers together
}
});
// Disable navigation sync for independent testing
browserSync({
server: './app',
ghostMode: {
clicks: true,
scroll: true,
location: false, // Let each browser navigate independently
forms: true
}
});Send custom events to all connected browsers for application-specific synchronization.
/**
* Socket.IO namespace for sending custom events
*/
sockets: {
/** Emit event to all connected browsers */
emit(event: string, data?: any): void;
/** Listen for events from browsers */
on(event: string, callback: (data: any) => void): void;
};Usage Examples:
const bs = require('browser-sync').create();
bs.init({
server: './app'
});
// Send custom events to all browsers
if (bs.active) {
// Notify browsers of server-side events
bs.sockets.emit('custom:notification', {
message: 'Data updated',
timestamp: Date.now()
});
// Trigger custom animations
bs.sockets.emit('ui:highlight', {
selector: '.updated-content'
});
// Send configuration updates
bs.sockets.emit('config:theme', {
theme: 'dark'
});
}
// Listen for events from browsers (in your client-side code)
/*
<script>
const socket = io('/browser-sync');
socket.on('custom:notification', function(data) {
showNotification(data.message);
});
socket.on('ui:highlight', function(data) {
document.querySelector(data.selector).classList.add('highlight');
});
</script>
*/Configure performance-related settings for synchronization events.
/**
* Performance tuning for synchronization
*/
interface SyncPerformanceConfig {
/** Throttle scroll events (ms) */
scrollThrottle?: number;
/** Connection timeout settings */
socket?: {
/** Socket.IO path (default: "/browser-sync/socket.io") */
path?: string;
/** Client path (default: "/browser-sync") */
clientPath?: string;
/** Socket namespace */
namespace?: string | Function;
/** Socket.IO server options */
socketIoOptions?: any;
/** Socket.IO client configuration */
socketIoClientConfig?: any;
};
}Usage Examples:
const browserSync = require('browser-sync');
// Performance-optimized setup
browserSync({
server: './app',
scrollThrottle: 100, // Reduce scroll event frequency
socket: {
path: '/bs/socket.io',
clientPath: '/bs',
socketIoOptions: {
transports: ['websocket'] // Use only websockets
}
}
});
// High-frequency synchronization for precise testing
browserSync({
server: './app',
scrollThrottle: 16, // ~60fps scroll sync
socket: {
socketIoOptions: {
pingInterval: 5000,
pingTimeout: 3000
}
}
});Monitor and debug synchronization state and connected clients.
/**
* Event emitter for synchronization events
*/
emitter: EventEmitter;Usage Examples:
const bs = require('browser-sync').create();
bs.init({
server: './app'
});
// Monitor client connections
bs.emitter.on('client:connected', (client) => {
console.log('New client connected:', client.id);
});
bs.emitter.on('client:disconnected', (client) => {
console.log('Client disconnected:', client.id);
});
// Monitor synchronization events
bs.emitter.on('browser:reload', () => {
console.log('Browsers reloading...');
});
bs.emitter.on('file:changed', (file) => {
console.log('File changed:', file);
});
// Log synchronization activity
bs.emitter.on('socket:connected', (socket) => {
console.log('Socket connected from:', socket.handshake.address);
});