Browsersync API

Our API is incredibly simple & powerful. You can use it to create your own tiny node program for local development or integrate with other tools. To use it, simply require the Browsersync module like you would any other. This will give you access to the public methods detailed below.

Pre 2.0.0 syntax
Previously we allowed methods to be called directly on the module export like this: 

// require the module as normal
var browserSync = require("browser-sync");

// Start the server
browserSync({server: "./app"});

// Call methods like reload
browserSync.reload("core.css");

Post 2.0.0 syntax (recommended)
Whilst the above is still supported, we now recommend the following instead. Calling .create() means you get a unique reference & allows you to create multiple servers or proxies. 

// require the module as normal
var bs = require("browser-sync").create();

// .init starts the server
bs.init({
    server: "./app"
});

// Now call methods on bs instead of the
// main browserSync module export
bs.reload("*.html");

Create a Browsersync instance

  • name
  • Type: String

  • an identifier that can used for retrieval later

// create an unnamed instance
var bs = require("browser-sync").create();

// create a named instance
var bs = require("browser-sync").create('My server');


// create multiple
var bs1 = require("browser-sync").create('Server 1');
var bs2 = require("browser-sync").create('Server 2');

Get a single instance by name. This is useful if you have your build scripts in separate files

// Create an named instance in one file...
var bs = require("browser-sync").create('My Server');

// Start the Browsersync server
bs.init({
    server: true
});

// now, retrieve the instance in another file...
var bs = require("browser-sync").get('My server');

// and call any methods on it.
bs.watch('*.html').on('change', bs.reload);

Check if an instance has been created.

Start the Browsersync service. This will launch a server, proxy or start the snippet mode depending on your use-case.

  • config
  • Type: Object [optional]

  • This is the main configuration for your Browsersync instance and can contain any of the available options If you do not pass a config an argument for configuration, Browsersync will still run; but it will be in the snippet mode

  • cb
  • Type: Function [optional]

  • If you pass a callback function, it will be called when Browsersync has completed all setup tasks and is ready to use. This is useful when you need to wait for information (for example: urls, port etc) or perform other tasks synchronously.

var bs = require("browser-sync").create();

// Start a Browsersync static file server
bs.init({
    server: "./app"
});

// Start a Browsersync proxy
bs.init({
    proxy: "http://www.bbc.co.uk"
});

The reload method will inform all browsers about changed files and will either cause the browser to refresh, or inject the files where possible.

  • arg
  • Type: String | Array | Object [optional]

  • The file or files to be reloaded.

// browser reload
bs.reload();

// single file
bs.reload("styles.css");

// multiple files
bs.reload(["styles.css", "ie.css"]);

// Since 2.6.0 - wildcards to reload ALL css files
bs.reload("*.css");

The stream method returns a transform stream and can act once or on many files.

  • opts
  • Type: Object [optional]

  • Configuration for the stream method

Note: requires at least version 2.6.0

// Compile SASS & auto-inject into browsers
gulp.task('sass', function () {
    return gulp.src('scss/styles.scss')
        .pipe(sass({includePaths: ['scss']}))
        .pipe(gulp.dest('css'))
        .pipe(bs.stream());
});

// Provide `once: true` to restrict reloading to once per stream
gulp.task('templates', function () {
    return gulp.src('*.jade')
        .pipe(jade())
        .pipe(gulp.dest('app'))
        .pipe(bs.stream({once: true}));
});

// Provide a filter to stop unwanted files from being reloaded
gulp.task('less', function () {
    return gulp.src('*.less')
        .pipe(less())
        .pipe(gulp.dest('css'))
        .pipe(bs.stream({match: "**/*.css"}));
});

Helper method for browser notifications

  • msg
  • Type: String | HTML

  • Can be a simple message such as 'Connected' or HTML

  • timeout
  • Type: Number [optional]

  • How long the message will remain in the browser. @since 1.3.0

var bs = require("browser-sync").create();

// Text message
bs.notify("Compiling, please wait!");

// HTML message
bs.notify("HTML <span color='green'>is supported</span> too!");

// Since 1.3.0, specify a timeout
bs.notify("This message will only last a second", 1000);

This method will close any running server, stop file watching & exit the current process.

var bs = require("browser-sync").create();

// Start the server
bs.init({server: "./app"});

// Quit the server after 5 seconds
setTimeout(function () {
    bs.exit();
}, 5000);

Stand alone file-watcher. Use this along with Browsersync to create your own, minimal build system

  • patterns
  • Type: String

  • Glob patterns for files to watch

  • opts
  • Type: Object [optional]

  • Options to be passed to Chokidar - check what's available in their docs

  • fn
  • Type: Function [optional]

  • Callback function for each event.

Note: requires at least version 2.6.0

// Create a Browsersync instance
var bs = require("browser-sync").create();

// Listen to change events on HTML and reload
bs.watch("*.html").on("change", bs.reload);

// Provide a callback to capture ALL events to CSS
// files - then filter for 'change' and reload all
// css files on the page.
bs.watch("css/*.css", function (event, file) {
    if (event === "change") {
        bs.reload("*.css");
    }
});

// Now init the Browsersync server
bs.init({
    server: "./app"
});

Method to pause file change events

Method to resume paused watchers

The internal Event Emitter used by the running Browsersync instance (if there is one). You can use this to emit your own events, such as changed files, logging etc.

var bs = require("browser-sync").create();

// Listen for the `init` event
bs.emitter.on("init", function () {
    console.log("Browsersync is running!");
});

bs.init(config);

A simple true/false flag that you can use to determine if there's a currently-running Browsersync instance.

var bs = require("browser-sync").create();

// -> false as .init has not yet been called
console.log(bs.active);

bs.init(config, function (err, bs) {

    // -> now true since BS is running now
    console.log(bs.active);
});

A simple true/false flag to determine if the current instance is paused

Access to client-side socket for emitting events

Jump to...