Core functionality for creating, managing, and controlling browser-sync instances. Browser-sync supports both singleton usage and named instances for managing multiple servers simultaneously.
Start browser-sync with configuration options. Can be used as singleton or with named instances.
/**
* Initialize a browser-sync instance with configuration
* @param config - Configuration options object
* @param callback - Optional callback when server is ready
* @returns BrowserSyncInstance
*/
function browserSync(config?: BrowserSyncConfig, callback?: (err: Error, bs: BrowserSyncInstance) => void): BrowserSyncInstance;
/**
* Alias for browserSync() - initialize instance
*/
browserSync.init(config?: BrowserSyncConfig, callback?: Function): BrowserSyncInstance;Usage Examples:
const browserSync = require('browser-sync');
// Basic server initialization
browserSync({
server: './dist',
files: ['./dist/**/*']
});
// With callback
browserSync({
proxy: 'localhost:3000'
}, function(err, bs) {
if (err) {
console.error('Browser-sync error:', err);
return;
}
console.log('Browser-sync is ready!');
console.log('Access URLs:', bs.getOption('urls'));
});Create a named browser-sync instance for managing multiple servers or different configurations.
/**
* Create a named browser-sync instance
* @param name - Optional identifier for the instance
* @returns BrowserSyncInstance
*/
browserSync.create(name?: string): BrowserSyncInstance;Usage Examples:
const browserSync = require('browser-sync');
// Create named instances
const bs1 = browserSync.create('server1');
const bs2 = browserSync.create('server2');
// Initialize each with different configs
bs1.init({
server: './app',
port: 3000,
files: ['./app/**/*.html']
});
bs2.init({
proxy: 'localhost:8080',
port: 3001,
files: ['./assets/**/*.css']
});
// Create instance with auto-generated name
const bs3 = browserSync.create();Retrieve an existing browser-sync instance by name. Useful for accessing instances across different modules or files.
/**
* Get an existing instance by name
* @param name - Instance identifier
* @returns BrowserSyncInstance
* @throws Error if instance not found
*/
browserSync.get(name: string): BrowserSyncInstance;Usage Examples:
const browserSync = require('browser-sync');
// In one file
const bs = browserSync.create('myapp');
bs.init({ server: './dist' });
// In another file
try {
const bs = browserSync.get('myapp');
bs.reload('*.css');
} catch (err) {
console.error('Instance not found:', err.message);
}Check if a browser-sync instance with the given name exists.
/**
* Check if an instance exists
* @param name - Instance identifier
* @returns true if instance exists, false otherwise
*/
browserSync.has(name: string): boolean;Usage Examples:
const browserSync = require('browser-sync');
if (browserSync.has('myapp')) {
const bs = browserSync.get('myapp');
bs.reload();
} else {
const bs = browserSync.create('myapp');
bs.init({ server: './build' });
}Methods available on browser-sync instances for controlling server state.
/**
* Stop the server, file watching, and exit process
*/
exit(): void;
/**
* Pause file change events
*/
pause(): void;
/**
* Resume paused file watchers
*/
resume(): void;
/**
* Get configuration option value
* @param key - Configuration key to retrieve
* @returns Configuration value
*/
getOption(key: string): any;Usage Examples:
const bs = browserSync.create();
bs.init({
server: './app',
files: ['./app/**/*']
});
// Pause file watching during build process
bs.pause();
runBuildProcess().then(() => {
bs.resume();
bs.reload();
});
// Get configuration values
const port = bs.getOption('port');
const urls = bs.getOption('urls');
console.log(`Server running at ${urls.local}`);
// Clean shutdown
process.on('SIGINT', () => {
bs.exit();
});Properties available on browser-sync instances for monitoring state.
/**
* Internal event emitter for custom events
*/
emitter: EventEmitter;
/**
* True if instance is currently running
*/
active: boolean;
/**
* True if instance is paused
*/
paused: boolean;
/**
* Socket.IO namespace for client communication
*/
sockets: any;Usage Examples:
const bs = browserSync.create();
bs.init({ server: './app' });
// Check instance state
if (bs.active) {
console.log('Browser-sync is running');
}
if (bs.paused) {
console.log('File watching is paused');
}
// Listen to internal events
bs.emitter.on('service:running', (data) => {
console.log('Service started:', data);
});
// Emit custom events to browsers
if (bs.active) {
bs.sockets.emit('custom:event', { message: 'Hello browsers!' });
}Static properties and methods available on the browser-sync module.
/**
* Array of all created instances
*/
browserSync.instances: BrowserSyncInstance[];
/**
* Reset module state (primarily for testing)
*/
browserSync.reset(): void;Usage Examples:
const browserSync = require('browser-sync');
// Create multiple instances
const bs1 = browserSync.create('app1');
const bs2 = browserSync.create('app2');
// Check all instances
console.log('Total instances:', browserSync.instances.length);
browserSync.instances.forEach((instance, index) => {
console.log(`Instance ${index}:`, instance.name, 'Active:', instance.active);
});
// Reset all instances (testing)
browserSync.reset();
console.log('Instances after reset:', browserSync.instances.length);