Working with a Config File

To create a config file, move into your project directory (the root folder of your website) and run:

browser-sync init

This will create a bs-config.js file that has some default settings, as well as some comments/guidelines. We'll look at all the options in detail shortly, but just so you know, you can now simply run:

browser-sync

##Options

###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"]

###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: Object
• Required property: host
• Optional property: port (defaults to 80)

Enter the hostname & port of your existing server to use BrowserSync with it.

NOTE: "localhost" not supported here, you'll have to configure your server to run on something like 127.0.0.1 or 0.0.0.0 instead.

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

• Type: Object
• Required property: baseDir
• 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 a specific index filename
server: {
    baseDir: "app",
    index: "index.htm"
}

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

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

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

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

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