Skip to content

2.12.1

Compare
Choose a tag to compare
@shakyShane shakyShane released this 11 Apr 18:30
· 558 commits to master since this release

As work continues on Browsersync V3, I've decided to take some time to back-port some improvements that have been discovered during the re-write. Many new features are not compatible with the architecture of this 2.x master branch, but those that are have made it into this 2.12 release.

Proxy

  • Add proxyReq & proxyRes to better align with http-proxy API - this allows you to modify the request before and after it hits the target.
  • Remove foxy module, bring proxy code into core. There was too much duplication & glue-code caused by having the proxy module separate and given they are intrinsically linked, it made sense to keep all of the logic together.

Middleware

  • Allow middleware to be registered per-route. Previously, if you wanted to only apply a middleware based on a route, you had to check the url manually, now you can mix & match 'global' middleware that affect every request with more targeted ones that only act when a particular
    route is hit. (see below for examples)

CLI

  • Switch from meow to yargs - for more features re: processing CLI input
  • Allow dot notation - to enable nested properties (eg: --proxy.ws)
  • Allow multiple items per option (eg: --files "*.html" "*.css")
  • Allow per-command help (eg: browser-sync start --help, browser-sync recipe --help etc)
  • Add short-hand alias for common options (eg: -s for server, -p for proxy etc)
  • Accept config from browser-sync key in package.json #1040
  • Allow flags to override all other forms of config

Plugins

  • Allow options in query strings - a big help when using the cli + plugins
    • (eg: browser-sync start -s --plugins bs-html-injector?files[]=*.html)

Snippet

  • Append snippet to end of document - by far the most commonly reported bug is a result of the deliberately simple regex used to insert the script tag directly after the first <body> tag. During testing for V3 I discovered that every single browser that we support is more than happy to accept a JS file that is loaded as the final thing on the page (even after the body/html tags) - this discovery alone should solve the countless hours that have been consumed reporting & replying to issues related to this.

Bug fixes

  • Always show 'codeSync' option - in sync-option in UI - #931 #802
  • Don't clobber existing url params on injected files - part of #687

Examples

Below are a few examples showing what is now possible in 2.12.0

Proxy - proxyReq & proxyRes

proxy: {
    target: "http://www.bbc.co.uk",
    /**
     * Functions given here will be called with the proxy 
     * request object *before* it hits your application
     */
    proxyReq: [
        function (proxyReq) {
            proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
        }
    ],
    /**
     * Functions given here will be called with the response 
     * object *before* it hits the browser
     */
    proxyRes: [
        /**
         * Here you have access to the raw response from your
         * application *before* it hits the browser
         */
        function (res) {
            res.headers['some-other-header'] = 'value';
        }
    ]
}

Middleware - applied on a per-route basis

Before - you needed to check the url manually

middleware: [function (req, res, next) {
    if (req.url.match(/^\/api/)) {
        // some middleware logic
    } else {
        next();
    }
}]

After - define the route up front

middleware: [
    {
        route: "/api",
        handle: function (req, res, next) {
            // some middleware logic
        }
    }
]

Mix and match - some middleware are global, some per-route. No problem. Here's an example where 2 global middleware apply to every route, and one applies to /api only

middleware: [
    require("compression")(), // global gzip middleware
    function (req, res, next) {
       // some other generic middleware
       next();
    },
    {
        route: "/api", // per-route
        handle: function (req, res, next) {
            // some middleware logic
            // like handing the request off to a proxy etc
        }
    }
]

CLI improvements

new short hand examples

  • -p = --proxy
  • -s = --server
  • -f = --files
  • -b = --browser
  • -c = --config
  • --ss = --serveStatic
# Start a server from the `app` directory, watching all files
$ browser-sync start -s 'app' -f 'app'

# Proxy a PHP app + serve static files & watch them
$ browser-sync start -p 'mylocal.dev' --ss 'public' -f 'public'

# Start Browsersync from a config file
$ browser-sync start -c conf/browser-sync.js

# Start Browsersync from a config file with overriding flags
$ browser-sync start -c conf/browser-sync.js --port 4000

inline plugin options

# 1. Start a server from the `app` directory
# 2. Register the bs-html-injector plugin with files: ['*.html'] option
browser-sync start -s 'app' --plugins bs-html-injector?files[]=*.html 

Have fun!

This is meant to be a non-breaking-change release, so please inform me if you encounter any issues. :)