browser-sync

What is browser-sync?

Browser-sync is a powerful tool for web developers that provides live reloading, synchronized browser testing, and other features to streamline the development process. It helps in creating a seamless development experience by automatically refreshing the browser whenever files are changed, and it can also synchronize interactions across multiple devices.

What are browser-sync's main functionalities?

Live Reloading

This feature allows the browser to automatically reload whenever files in the specified directory are changed. The code sample sets up a server to serve files from the 'app' directory and watches for changes in any files within that directory, triggering a reload when changes are detected.

const browserSync = require('browser-sync').create();
browserSync.init({
  server: './app'
});
browserSync.watch('app/**/*.*').on('change', browserSync.reload);

Synchronized Browsing

Synchronized browsing ensures that interactions like clicks and scrolls are mirrored across all connected devices. The code sample initializes Browser-sync with ghost mode enabled for clicks and scrolls, allowing these interactions to be synchronized.

const browserSync = require('browser-sync').create();
browserSync.init({
  server: './app',
  ghostMode: {
    clicks: true,
    scroll: true
  }
});

Proxying an Existing Server

This feature allows Browser-sync to act as a proxy for an existing server, enabling live reloading and synchronized browsing without changing the server configuration. The code sample sets up Browser-sync to proxy requests to 'yourlocal.dev'.

const browserSync = require('browser-sync').create();
browserSync.init({
  proxy: 'yourlocal.dev'
});

Other packages similar to browser-sync

live-server

Live-server is a simple development HTTP server with live reload capability. It is easier to set up compared to Browser-sync but offers fewer features. It is ideal for quick prototyping and small projects.

webpack-dev-server

Webpack-dev-server is a development server that provides live reloading and HMR (Hot Module Replacement) for projects using Webpack. It is more complex to set up but integrates deeply with the Webpack build process, making it suitable for larger projects with complex build requirements.

gulp-connect

Gulp-connect is a plugin for Gulp that provides a web server with live reload capability. It is useful for projects that already use Gulp for task automation, offering a seamless way to add live reloading to the development workflow.

README

browser-sync

Keep multiple browsers & devices in sync when building websites.

##Features

1. Scroll - I can keep your pages in sync when scrolling.
2. Forms - You fill out a form in one browser, I'll copy the data to all the others.
3. Links - I'll watch your clicks and make all the browser follow you.
4. CSS injecting - I can even watch your CSS files & inject them when they change.
5. Live Reload - I can also watch files like HTML and PHP & when they change I can reload all browsers for you.
6. Built-in Server - Yep, I can serve static files too if you need me to
7. Use with any back-end setup - Browser-sync includes a proxy option so that it can be used with any existing PHP, Rails, Python, Node or ASP.net setup.

##When is it useful? It's pretty useful when used with a single browser, watching a CSS file for changes & injecting it. But the real power comes when you're building responsive sites and using multiple devices/monitors because it can keep all browsers in sync & make your workflow much faster.

##Support If you've found Browser-sync useful and would like to contribute to its continued development & support, please feel free to send a donation of any size - it would be greatly appreciated!

##Using Grunt? There's a plugin for that

##How to install it?

npm install -g browser-sync

####If that doesn't work on a mac, try

sudo npm install -g browser-sync

##How to use it Browser-sync is a command-line tool & the -g from the command above makes it available everywhere on your system. Just cd into your website and run one of the commands below. If any further instructions are needed, you'll be notified on the command line.

###Watching files

Watch ALL CSS files in a directory for changes

browser-sync --files "app/css/*.css"

Watch ALL CSS files & HTML files in a directory for changes

browser-sync --files "app/css/*.css, app/*.html"

###Watching files + your existing Server (proxy)

Using a local.dev vhost

browser-sync --proxy "local.dev" --files "app/css/*.css"

Using a local.dev vhost with PORT

browser-sync --proxy "local.dev:8001" --files "app/css/*.css"

Using a an IP based host

browser-sync --proxy "192.167.3.2:8001" --files "app/css/*.css"

###Watching files + built-in static server (for html, js & css)

Watch ALL CSS files for changes with a static server

browser-sync --files "app/css/*.css" --server

Watch ALL CSS files for changes with a static server & specify that the base dir should be "app"

browser-sync --files "app/css/*.css" --server "app"

Watch ALL CSS files for changes with a static server & specify that the base dir should be "app" & specify the index file (note the missing l)

browser-sync --files "app/css/*.css" --server "app" --index "index.htm"

Watch ALL CSS files for changes with a static server & specify that the base dir should be "app" & with ghostMode disabled

browser-sync --files "app/css/*.css" --server "app" --ghostMode false

###Example config file with proxy If you want to, you can provide a config file instead of having to remember all of the commands above. Also, a config file allows you to be more specific with options. Here's an example of one that you would put in the root of your project.

module.exports = {
    files: "app/css/**/*.css",
    host: "192.168.1.1",
    ghostMode: {
        links: true,
        forms: true,
        scroll: true
    },
    proxy: {
        host: "local.dev" // your existing vhost
    }
};

Now, if you called the file config.js, you'd simple run

browser-sync --config config.js

##All available options for use in config file

###files - (default: null)

// single file
files: "app/css/style.css"

// multiple files
files: ["app/css/style.css", "app/css/ie.css"]

// multiple files with glob
files: "app/css/*.css"

// multiple globs
files: ["app/css/*.css", "app/**.*.html"]

###debugInfo - (default: true)

// Don't fill my terminal with info
debugInfo: false

// Give me as much info as possible
debugInfo: true

###host - (default: null)

// Leave this set as null & browser-sync will try to figure out the correct IP to use. (about 90% accurate)
host: null

// Override host detection if you know the correct IP to use
host: "192.168.1.1"

###ghostMode - (default: { links: true, forms: true, scroll: true} )

// Here you can disable/enable each feature individually
ghostMode: {
    links: true,
    forms: true,
    scroll: false
}

// Or switch them all off in one go
ghostMode: false

###proxy - (default: null) NOTE: "localhost" not supported here, try to use something else like "0.0.0.0" instead if you need to.

// use your existing vhost setup
proxy: {
	host: "local.dev"
}

// use your existing vhost setup with a specific port
proxy: {
	host: "local.dev",
	port: 8001
}

// use an IP-based host (like the built-in php server for example)
proxy: {
	host: "192.168.0.4",
	port: 8001
}

###server - (default: null) Server should only be used for static HTML, CSS & JS files. It should NOT be used if you have an existing PHP, Wordpress, Rails setup. That's what the proxy above is for.

// Serve files from the app directory
server: {
    baseDir: "app"
}

// Serve files from the app directory, with a specific index filename
server: {
    baseDir: "app",
    index: "index.htm"
}

// Serve files from the root directory
server: {
    baseDir: "./"
}

###ports - (default: null) Browser-sync will detect up to 3 available ports to use within a fixed range. You can override this if you need to.

// only use ports within a certain range
ports: {
    min: 3000,
    max: 3100
}

// you can also specify just a minimum
ports: {
    min: 3000
}

###open - (default: true) - when used with server

// Launch a browser window at the correct location
open: true

// Stop the browser from automatically opening
open: false

###notify - (default: true) Browser-sync will flash a quick message in all connected browsers to confirm that CSS injection has taken place (useful when you're not sure whether the injection worked, or whether your CSS didn't make a difference)

// Tell me when a CSS file was injected
notify: true

// Don't show any notifications in the browser.
notify: false

#Full config file example with Server Save this as anything-you-like.js

module.exports = {
    files: "app/css/**/*.css",
    debugInfo: true,
    host: "192.168.1.1",
    ghostMode: {
        links: true,
        forms: true,
        scroll: true
    },
    server: {
        baseDir: "app"
    },
    open: false,
    notify: true
};

#Full config file example with Proxy Save this as anything-you-like.js

module.exports = {
    files: "app/css/**/*.css",
    debugInfo: true,
    host: "192.168.1.1",
    ghostMode: {
        links: true,
        forms: true,
        scroll: true
    },
	proxy: {
		host: "local.dev" // your existing vhost setup.
	},
    open: true,
    notify: true
};

Now you can use it by calling it from the command-line

browser-sync --config anything-you-like.js

#Contributing Fork this repo, clone it and then run

npm install

###Testing Tests are split into two categories: Client & Server

Client-side tests Client-side tests are located in test/client-script/*

// Run the client-side tests & exit

grunt test:client

// Run the client-side tests & re-run on every file-change.

grunt karma:watch

Server-side tests Server-side tests are located in test/new-server

// Run the server-side tests & exit

grunt test:server

// Run the server-side tests & re-run on every file-change.

grunt watch

// Run the server-side tests & client-side tests once & exit.

grunt test

This is a brand new project so expect bugs & be sure to report them.

License

Copyright (c) 2013 Shane Osbourne Licensed under the MIT license.