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

notifications-ui.mddocs/

Notifications and UI

Browser-sync provides a browser notification system for displaying messages to users and a web-based control UI for managing connected devices, monitoring synchronization, and controlling server settings in real-time.

Capabilities

Browser Notifications

Display notifications in connected browsers for build status, errors, or custom messages.

/**
 * Display notification in connected browsers
 * @param message - Notification content (text or HTML)
 * @param timeout - Display duration in milliseconds (default: 2000)
 */
notify(message: string | HTML, timeout?: number): void;

Usage Examples:

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

bs.init({
    server: './app'
});

// Simple text notification
bs.notify('Build completed successfully!');

// HTML notification with styling
bs.notify('<span style="color: green;">✓ Tests passed</span>');

// Notification with custom timeout
bs.notify('Compiling...', 5000); // Show for 5 seconds

// Integration with build tools
const gulp = require('gulp');

gulp.task('sass', function() {
    return gulp.src('./scss/*.scss')
        .pipe(sass().on('error', function(err) {
            bs.notify(`<span style="color: red;">Sass error: ${err.message}</span>`, 10000);
        }))
        .pipe(gulp.dest('./css'))
        .pipe(bs.stream())
        .on('end', function() {
            bs.notify('Sass compilation complete');
        });
});

// Error notifications
function buildScripts() {
    try {
        // Build process...
        bs.notify('Scripts built successfully');
    } catch (error) {
        bs.notify(`Build failed: ${error.message}`, 8000);
    }
}

Control UI

Web-based interface for managing browser-sync settings and monitoring connected devices.

/**
 * UI configuration options
 */
ui?: boolean | UIConfig;

interface UIConfig {
    /** Port for the UI server (default: 3001) */
    port?: number;
    /** Weinre configuration for remote debugging */
    weinre?: {
        port?: number;
    };
}

Usage Examples:

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

// Enable UI with default settings
browserSync({
    server: './app',
    ui: true // UI available at http://localhost:3001
});

// Custom UI port
browserSync({
    server: './app',
    ui: {
        port: 8080 // UI available at http://localhost:8080
    }
});

// Disable UI completely
browserSync({
    server: './app',
    ui: false
});

// UI with weinre for remote debugging
browserSync({
    server: './app',
    ui: {
        port: 3001,
        weinre: {
            port: 8001
        }
    }
});

Browser Auto-Opening

Control which browsers open automatically when browser-sync starts.

/**
 * Auto-open browser configuration
 */
open?: boolean | string | "local" | "external" | "ui" | "ui-external" | "tunnel";

/**
 * Specific browser(s) to open
 */
browser?: string | string[];

/**
 * Start path for opened browser
 */
startPath?: string;

Usage Examples:

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

// Open local URL in default browser
browserSync({
    server: './app',
    open: true // or 'local'
});

// Open external URL (accessible from other devices)
browserSync({
    server: './app',
    open: 'external'
});

// Open browser-sync UI instead of site
browserSync({
    server: './app',
    open: 'ui'
});

// Don't open any browser
browserSync({
    server: './app',
    open: false
});

// Open specific browser
browserSync({
    server: './app',
    browser: 'google chrome'
});

// Open multiple browsers
browserSync({
    server: './app',
    browser: ['firefox', 'chrome', 'safari']
});

// Open with specific start path
browserSync({
    server: './app',
    open: true,
    startPath: '/dashboard'
});

Logging Configuration

Control console output and logging behavior for notifications and general information.

/**
 * Console output level
 */
logLevel?: "silent" | "info" | "debug" | "warn";

/**
 * Console logging prefix (default: "Browsersync")
 */
logPrefix?: string;

/**
 * Log client connections (default: false)
 */
logConnections?: boolean;

/**
 * Log file changes (default: true)
 */
logFileChanges?: boolean;

/**
 * Log snippet in snippet mode (default: true)
 */
logSnippet?: boolean;

Usage Examples:

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

// Minimal logging
browserSync({
    server: './app',
    logLevel: 'silent' // No console output
});

// Debug mode with detailed logging
browserSync({
    server: './app',
    logLevel: 'debug',
    logConnections: true, // Log when browsers connect/disconnect
    logFileChanges: true  // Log file change events
});

// Custom log prefix
browserSync({
    server: './app',
    logPrefix: 'MyApp',
    logLevel: 'info'
});

// Production-friendly logging
browserSync({
    proxy: 'localhost:3000',
    logLevel: 'warn', // Only show warnings and errors
    logConnections: false,
    logFileChanges: false,
    logSnippet: false
});

Notification Styling

Customize the appearance and behavior of browser notifications.

/**
 * Configure notification display behavior and styling
 */
interface NotificationOptions {
    /** Default timeout for notifications (ms) */
    timeout?: number;
    /** Custom CSS for notification styling */
    styles?: string;
    /** Position of notifications */
    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
}

Usage Examples:

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

bs.init({
    server: './app'
});

// Styled notifications
bs.notify(`
    <div style="
        background: linear-gradient(45deg, #667eea, #764ba2);
        color: white;
        padding: 15px;
        border-radius: 5px;
        font-family: Arial, sans-serif;
        box-shadow: 0 4px 8px rgba(0,0,0,0.2);
    ">
        <strong>✓ Build Complete</strong><br>
        All files processed successfully
    </div>
`, 4000);

// Status-based notification helper
function showStatus(type, message, timeout = 3000) {
    const colors = {
        success: '#4CAF50',
        error: '#F44336', 
        warning: '#FF9800',
        info: '#2196F3'
    };
    
    const icons = {
        success: '✓',
        error: '✗',
        warning: '⚠',
        info: 'ℹ'
    };
    
    bs.notify(`
        <div style="
            background: ${colors[type]};
            color: white;
            padding: 10px 15px;
            border-radius: 4px;
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
        ">
            ${icons[type]} ${message}
        </div>
    `, timeout);
}

// Usage
showStatus('success', 'Sass compiled successfully');
showStatus('error', 'TypeScript compilation failed', 8000);
showStatus('warning', 'Deprecated API usage detected');

UI Features and Capabilities

The browser-sync UI provides various features for monitoring and controlling your development server.

UI Features:

  • Overview: Current server status, URLs, and connected devices
  • Sync Options: Toggle different synchronization features on/off
  • History: View recent file changes and reload events
  • Network Throttle: Simulate different network conditions
  • Weinre: Remote debugging for mobile devices
  • Plugins: Manage and configure loaded plugins

Usage Examples:

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

// Full-featured UI setup
browserSync({
    server: './app',
    ui: {
        port: 3001
    },
    // Enable features visible in UI
    ghostMode: {
        clicks: true,
        scroll: true,
        location: true,
        forms: {
            submit: true,
            inputs: true,
            toggles: true
        }
    },
    logConnections: true, // See connections in UI
    plugins: ['bs-html-injector'] // Plugins shown in UI
});

// Access UI programmatically
const bs = browserSync.create();
bs.init({ server: './app' });

// Get UI URL
const uiUrl = bs.getOption('urls').ui;
console.log('UI available at:', uiUrl);

Notification Integration Examples

Real-world examples of integrating notifications with build processes and development workflows.

Build Tool Integration:

// Webpack integration
const browserSync = require('browser-sync');
const bs = browserSync.create();

// In webpack.config.js
module.exports = {
    // ... webpack config
    plugins: [
        new (class {
            apply(compiler) {
                compiler.hooks.done.tap('BrowserSyncNotify', (stats) => {
                    if (stats.hasErrors()) {
                        bs.notify('Webpack build failed', 5000);
                    } else {
                        bs.notify('Webpack build completed');
                    }
                });
            }
        })()
    ]
};

// Test runner integration
function runTests() {
    return new Promise((resolve, reject) => {
        bs.notify('Running tests...', 1000);
        
        // Run your test suite
        exec('npm test', (error, stdout, stderr) => {
            if (error) {
                bs.notify(`Tests failed: ${error.message}`, 8000);
                reject(error);
            } else {
                bs.notify('All tests passed!', 3000);
                resolve(stdout);
            }
        });
    });
}

// File watcher with notifications
const chokidar = require('chokidar');

chokidar.watch('./src/**/*.js').on('change', (path) => {
    bs.notify(`File changed: ${path.split('/').pop()}`, 2000);
    
    // Trigger rebuild
    rebuild().then(() => {
        bs.notify('Rebuild complete');
        bs.reload();
    }).catch(err => {
        bs.notify(`Build error: ${err.message}`, 6000);
    });
});