Skip to content

Options 1.0

Jump to bottom Edit New page
Shane Osbourne edited this page Jun 20, 2014 · 3 revisions

These are all the available options that can be used with BrowserSync's bs-config.js file, the GruntJS Plugin, or through the API for things like Gulp

###files

  • Type: String | Array
  • Default: null

BrowserSync can watch your files as you work. Changes you make will either be injected into the page (CSS & images) or will cause all browsers to do a full-page refresh instead.

// 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", "app/js/**/*.js"]

###exclude

  • Type: Array
  • Default: null

All files are excluded by default anyway so it's better to be specific with your files option above instead of using this. But if you must, you can exclude certain directories/files here.

// exclude a single file from being watched
exclude: "app/css/style.min.css"

// exclude multiple files from being watched
exclude: ["app/css/style.min.css", "app/css/ie.min.css"]

// exclude entire directory (includes all sub-directories)
exclude: "app/css/dist"

// exclude multiple directories
exclude: ["app/css/dist", "app/img/dist"]

###proxy

  • Type: String

Enter your existing server url here. BrowserSync will wrap your vhost with a proxy URL to view your site.

// For BrowserSync versions above 0.7.0
// Using a vhost-based url
proxy: "local.dev"

// Using a localhost address with a port
proxy: "localhost:8888"

// Using localhost sub directories
proxy: "localhost/site1"

// For BrowserSync versions below 0.7.0
// Using a vhost-based url
proxy: {
    host: "local.dev"
}

// Using a localhost address with a port
proxy: {
    host: "localhost",
    port: 8888
}

###server

  • Type: Object
  • Required property: baseDir
  • Optional property: middleware
  • Optional Property: directory (default: false)
  • Optional property: index (defaults to "index.html")

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 directory listing
server: {
    baseDir: "app",
    directory: true
}

// Multiple base directories
server: {
    baseDir: ["app", "dist"]
}

// 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: "./"
}

// Custom Middleware
server: {
    baseDir: "./",
    middleware: function (req, res, next) {
        console.log("Hi from middleware");
        next();
    }
}

// Multiple custom Middlewares
server: {
    baseDir: "./",
    middleware: [
        function (req, res, next) {
            console.log("Hi from first middleware");
            next();
        },
        function (req, res, next) {
            console.log("Hi from the second middleware");
            next();
        }
    ]
}

###tunnel

  • Type: String|boolean
  • Default: null

NEW - if you would like to use a public URL to work on your site, set this to true. You can also provide a string that will be used as the sub-domain (if available)

// Tunnel the BrowserSync server through a random Public URL
// -> http://randomstring23232.localtunnel.me
tunnel: true

// Attempt to use the URL "http://my-private-site.localtunnel.me"
tunnel: "my-private-site"

###online

  • Type: boolean
  • Default: none

If not set, BrowserSync will try to figure out if you're on a network or not. If this causes a slow-down for your start-up time, you can set it to true or false and skip the check. This is important because certain features (such as Tunnel, or XIP.IO) require a connection.

// Will not attempt to determine your network status, assumes you're ONLINE.
online: true

// Will not attempt to determine your network status, assumes you're OFFLINE
online: true

// Tunnel the BrowserSync server through a random Public URL
// -> http://randomstring23232.localtunnel.me
tunnel: true

// Attempt to use the URL "http://my-private-site.localtunnel.me"
tunnel: "my-private-site"

###browser

  • Type: String|Array
  • Default: default

If you allow BrowserSync to open the site for you, it will simply use your default browser, override that here. (note: names may be platform specific - experiment)

// Open the site in Chrome
browser: "google chrome"

// Open the site in Chrome & Firefox
browser: ["google chrome", "firefox"]

###hostnameSuffix

  • Type: String
  • Default: null

If you need something appending the hostname used by BrowserSync (such as xip.io), you can specify it here.

// Append '.xip.io' to the hostname. (eg: http://192.168.0.4.xip.io:3002)
hostnameSuffix: ".xip.io"

###injectChanges

  • Type: Boolean
  • Default: true

Browser Sync will attempt to inject changes where possible (such as CSS, Images). If your situation requires a full page reload instead, change this to false.

// Inject CSS changes
injectChanges: true,

// Don't try to inject, just do a page refresh
injectChanges: false,

###reloadDelay

  • Type: Number
  • Default: 0

You can specify a delay between a file being changed & the reload/injection happening in the browser. You may be useful if you have other things to do with the file (such as upload to a remote).

// Wait for 2 seconds before any browsers should try to inject/reload a file.
reloadDelay: 2000,

###logConnections

  • Type: Boolean
  • Default: true

The connection messages can quickly fill up your terminal window, switch them off if you like.

// Don't log connections
logConnections: false

###logLevel

  • Type: string
  • Default: info 
// Show me additional info about the process
logLevel: "debug"

// Just show basic info
logLevel: "info"

// output NOTHING to the commandline
logLevel: "silent"

###host

  • Type: String
  • Default: auto-detected

Browser-sync will choose an external IP to use for serving the files it needs. This will allow it to work on any device connected to your wifi network & is about 90% accurate. If it chooses the wrong one for you & you know which one it should use - plug it in here. (otherwise leave this set to null for auto-detect)

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

###ghostMode

  • Type: Object
  • Defaults:
    • clicks: true
    • location: false
    • forms: true
    • scroll: true
// Here you can disable/enable each feature individually
ghostMode: {
    clicks: true,
    location: true,
    forms: true,
    scroll: false
}

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

###port

  • Type: number

Browser-sync auto-detect an available port for you, but if you prefer to set it, you can do so here

port: 8080

###open

  • Type: Boolean
  • Default: true

BrowserSync will open up your default browser everytime you run it. You can override that here.

// Stop the browser from automatically opening
open: false

###startPath

  • Type: String
  • Default: null

If you want to open the browser at a specfic path, you can set it here.

// Open the first browser window at URL + "/info.php"
startPath: "/info.php"

###excludedFileTypes

Type: Array

Default: https://github.com/shakyShane/browser-sync/blob/master/lib/index.js#L31

If you experience problems loading files with BrowserSync, you may add file extensions to the 'exclude' list - which means BrowserSync will not attempt to modify them & just serve them normally. (useful if you have a file-type that is not in the default list above)

// Allow extra file-types to be used with BrowserSync
excludedFileTypes: ["mp2"]

###timestamps

  • Type: Boolean
  • Default: true

Browser-sync appends a timestamp to injected files to ensure the browser reloads the latest version, some workflows (like this one: http://www.youtube.com/watch?v=4r6yhimSmZg) may work better without it though.

// Don't append timestamps to injected files
timestamps: false

###debounce

  • Type: Number
  • Default: 0

You can specify a timeout for browser-sync to wait until files stop changing to trigger the change event. Useful for when you have a large number of files that may change all at once, all but one causing an unecessary trigger to the change event to reload the browser.

// Wait for 0.2 seconds since the last file changed to actually reload the browser
debounce: 200,

###scrollProportionally

  • Type: Boolean
  • Default: true

Set this to false if you'd prefer to have the scroll synced to the top of each viewport instead of proportionally.

scrollProportionally: false // Sync viewports to TOP position

###scrollThrottle

  • Type: Number
  • Default: 0

If you experience any problems with the scroll sync, you can throttle how quickly the events are sent. (0-200 works best)

scrollThrottle: 100 // only send scroll events every 100 milliseconds

###notify

  • Type: Boolean
  • 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
Add a custom footer
Add a custom sidebar
Clone this wiki locally