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 normalvar 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 normalvar 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( name ) ^ TOP

Create a Browsersync instance

name
Type: String

an identifier that can used for retrieval later

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

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

// create multiplevar bs1 = require("browser-sync").create('Server

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

.get( name ) ^ TOP

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

name
Type: String

// 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);

.has( name ) ^ TOP

Check if an instance has been created.

name
Type: String

.init( config, cb ) ^ TOP

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"

});

.reload( arg ) ^ TOP

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");

.stream( opts ) ^ TOP

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"}));
});

.notify( msg, timeout ) ^ TOP

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);

.exit() ^ TOP

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);
.watch( patterns, opts, fn ) ^ TOP

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 instancevar 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"

});

.pause() ^ TOP

Method to pause file change events

.resume() ^ TOP

Method to resume paused watchers

.emitter ^ TOP

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);

.active ^ TOP

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 calledconsole.log(bs.active);

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

// -> now true since BS is running now

console.log(bs.active);

});

.paused ^ TOP

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

.sockets ^ TOP

Access to client-side socket for emitting events