Using BrowserSync during Development to Live Reload Changes

BrowerSync is a NodeJs based tool that can automatically reload the active page in the Web browser when you make a change to a file in your Website. The idea is that you can much more quickly edit files in your site, and immediately see the change reflected in the browser without having to explicitly navigate or refresh the browser.

You can basically have your code and a live browser window side by side and as you make changes and save, you can immediately see the result of your change reflected in the browser. It's a very efficient way to work.

What do you need?

In order to use Browser Sync you need to install it which involves a few bit of kit:

So you start by making sure that NodeJs is installed and working. You should be able to go to a Windows command prompt and type:

node --version
npm --version

If these commands work, Node and NPM are installed. If not you'll have to install it. NPM is part of the Node Installation so it's a single install.

Next you need to install BrowserSync

npm install -g browser-sync

Running BrowserSync

Once BrowserSync has been installed, you can use the BrowserSync.prg file in your project directory to launch browsersync and navigate the browser. Doing this fires up a command window with the BrowserSync client command line tool that monitors for file changes and sends notifications to the browser to refresh itself when files that you specify have changed.

BrowserSync.prg is generated when your project is generated and it automatically adds common file types to monitor, and the URL of your site.

Behind the scenes the generated BrowserSync file looks like this:

*  BrowserSync
***  Function: Live Reload on save operations
***    Assume: Install Browser Sync requires Node/NPM:
***            npm install -g browser-sync
FUNCTION BrowserSync(lcUrl, lcPath, lcFiles)

   lcUrl = "localhost/usersecuritymanager"
IF EMPTY(lcPath)
   lcPath = LOWER(FULLPATH("..\web"))
IF EMPTY(lcFiles)
   lcFiles = "**/*.usm, **/*.wcs, **/*.wc, css/*.css, scripts/*.js, **/*.htm*"

lcOldPath = CURDIR()
CD (lcPath)

lcBrowserSyncCommand = "browser-sync start " +;
                       "--proxy " + lcUrl + " " + ;
                       "--files '" + lcFiles + "'"
RUN /n cmd /k &lcBrowserSyncCommand

*!*	? lcBrowserSyncCommand
*!*	_cliptext = lcBrowserSyncCommand

CD (lcOldPath)

DO UserSecurityManagerMain 

*   BrowserSync

After you DO BROWSERSYNC the browser opens at a proxy URL (http://localhost:3000 typically) and your site then works as it always does. However, if you make any change in any HTML, CSS, JS or Web Connection template file that is listed the current page is reloaded in the browser immediately.

Et voila - live browser reload of server pages as soon as you make any change.

How does BrowserSync work?

To work with Web Connection BrowserSync has to be used in Proxy mode, which means BrowserSync uses a custom URL (typically http://localhost:3000) and then forwards that request to your actual Web server. The proxy intercept is used to inject some JavaScript into the page that lets the Browser Sync console app communicate with a small service inside of the JavaScript payload using WebSockets. The main task is to notify the browser when there's a change in any file and forcing the browser to refresh itself. its own custom URL that you access.

The proxy is what makes it possible to detect changes and inject a WebSocket client into the Web page that communicates with the browser sync console app that executes. Browser sync detects changes to files on disk you specify and then can make the browser refresh itself to show the updated page.

The good news is that as a user you don't need to understand how it works - you can just partake in the magic of Live Browser Reload any time you make a change.


As cool as this tool is, it has a few issues that pop up infrequently.

Slow Downs or Pages not Refreshing

If you use BrowserSync for a while you may find that refreshing of pages - even manual refreshes - get really slow. This is usually caused by browser-sync getting out of sync requests and failing to properly refresh pages. It doesn't happen often but it does happen.

To fix, shut down the Browser Sync command window and then restart it with DO BrowserSync again. Once you do this connections and refreshes should be quick again.

No Windows/Basic Authentication

Any pages that require Windows authentication don't work with Browser-Sync as it doesn't understand the protocol. This means you can't access Web Connection admin pages.

To fix, for admin pages use the 'real' Web site URL rather than the Browser-Sync proxy pages. Note that Browser-Sync works fine with cookie based Session authentication in Web Connection so typical login applications will work fine.

More Info in Blog Post

I wrote up a more detailed discussion on Browser-Sync and Web Connection in a blog post:

© West Wind Technologies, 1996-2019 • Updated: 11/14/18
Comment or report problem with topic