Skip to content
Shane Osbourne edited this page Mar 20, 2014 · 15 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"


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

// 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();
        }
    ]
}

###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,

###debugInfo

  • Type: Boolean
  • Default: true
// Don't fill my terminal with info
debugInfo: false

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

###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
    • links: true
    • forms: true
    • scroll: true
// Here you can disable/enable each feature individually
ghostMode: {
    clicks: true,
    links: true,
    forms: true,
    scroll: false
}

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

###ports

  • Type: Object
  • Required property: min
  • Optional property: max

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

  • 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

###fileTimeout

  • Type: Number
  • Default: 1000

If you're using a pre-processor (like SASS) & you find that the file watching is erratic, you can increase the amount of time to wait after a file changed here. (only change this if you experience a problem, it will probably work just fine)

fileTimeout: 4000 // wait 4 seconds while SASS compiles

###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
Clone this wiki locally