BrowserSync Client-Side Script

3.0.4 verified Thu Apr 23 auth: no javascript maintenance

browser-sync-client is the essential client-side JavaScript component for the BrowserSync tool, enabling real-time browser synchronization and live reloading functionalities. As of its latest version 3.0.4, published approximately a year ago, it's typically bundled and injected by the main `browser-sync` server into web pages. This package does not follow a strict, predictable release cadence, and the core `browser-sync` project shows signs of being in a maintenance mode rather than active feature development. Its key differentiator is facilitating a synchronized development experience across multiple browsers and devices, mirroring scrolls, clicks, form inputs, and injecting CSS/JS changes without manual refreshes. It's a critical piece for front-end development workflows, especially when integrating with task runners like Gulp or Webpack, but it's not designed for direct developer import or interaction in application code.

Common errors

error Error: `node-gyp` failed to compile native addon. See the npm log for details. ↓

cause Missing Visual C++ build tools on Windows required by native dependencies of BrowserSync.

fix

Install windows-build-tools globally: npm install --global --production windows-build-tools or, for specific Visual Studio versions, npm install -g browser-sync --msvs_version=2013.

error TypeError: Cannot read properties of undefined (reading 'local') ↓

cause Attempting to access BrowserSync options using direct property access (e.g., `bs.options.urls.local`) after upgrading to `browser-sync` version 2.x or higher.

fix

Update your code to use the getIn method for accessing options: bs.options.getIn(['urls', 'local']).

error BrowserSync not connecting (no 'Connected to BrowserSync' notification) ↓

cause The client script failed to inject, a firewall is blocking the connection, or an incorrect host/port is configured.

fix

Verify that browser-sync is running and successfully injecting the script (check your browser's developer tools for the <script id='__bs_script__'> tag). Check firewall settings, ensure the configured host/port is accessible, and review browser-sync options like host, port, snippetOptions. If using a proxy, ensure it's correctly configured.

Warnings

gotcha The `browser-sync-client` package is not intended for direct `import` or `require()` in your application's JavaScript code. Its functionality is activated when the main `browser-sync` server injects a `<script>` tag into your HTML. Attempting to bundle or import it directly will not work as expected and is an incorrect usage pattern. ↓

fix Ensure you are running the `browser-sync` server (e.g., via CLI or build tool integration) which will automatically inject the client script. Do not add `<script>` tags manually unless explicitly opting out of automatic injection and providing a custom `scriptPath` in `browser-sync` options.

breaking When upgrading the main `browser-sync` package from `1.x` to `2.x`, the method for accessing options changed from direct property access (e.g., `bs.options.urls.local`) to an immutable `getIn()` method (e.g., `bs.options.getIn(['urls', 'local'])`). While this is a change in the server API, it affects how you configure or interact with `browser-sync` in your build scripts. ↓

fix Update your `browser-sync` configuration and API calls to use `bs.options.getIn([...])` for accessing nested options. Review the `browser-sync` documentation for specific changes if migrating.

gotcha On Windows, `browser-sync` (and by extension its dependencies, including `browser-sync-client` build process) can encounter errors related to `node-gyp` requiring Visual C++ runtime libraries during installation. This is a common issue with Node.js packages that have native dependencies. ↓

fix Install the necessary Visual C++ build tools. For Visual Studio 2013, use `npm install -g browser-sync --msvs_version=2013`. For newer versions, Microsoft provides `windows-build-tools` via `npm install --global --production windows-build-tools`.

deprecated The `browser-sync` project, and consequently `browser-sync-client`, has had an inactive release cadence for a year, with no new versions released recently. This indicates it may be in a maintenance-only state or considered discontinued, which could impact long-term support or compatibility with very new Node.js/browser environments. ↓

fix Evaluate the project's long-term viability for new projects. For existing projects, be aware that new features or compatibility fixes for future ecosystem changes may not be provided. Consider contributing to the project if critical updates are needed.

Install

npm install browser-sync-client

yarn add browser-sync-client

pnpm add browser-sync-client

Imports

browser-sync-client script injection
wrong
```
import 'browser-sync-client';
```
correct
```

<script async src='http://HOST:3000/browser-sync/browser-sync-client.js?v=VERSION'></script>
```
This package is a client-side script designed to be injected into HTML by the BrowserSync server, typically before the `</body>` tag. Developers should not attempt to `import` or `require()` it directly in their application code. The correct usage involves configuring the main `browser-sync` package, which then handles the injection. The injected script establishes a WebSocket connection for live updates.
BrowserSync instance for control
wrong
```
import { client } from 'browser-sync-client';
```
correct
```
import browserSync from 'browser-sync';
// ... then use browserSync.reload() or other API calls
```
While `browser-sync-client` runs in the browser, developers interact with its functionalities through the main `browser-sync` package's API in their Node.js build scripts. There are no direct client-side JavaScript APIs intended for application code interaction within `browser-sync-client` itself.

Quickstart

This quickstart demonstrates how to set up `browser-sync` with Gulp to serve static files, compile Sass, and automatically inject CSS changes or trigger full page reloads for HTML and JavaScript, leveraging the client-side script for synchronization.

const gulp = require('gulp');
const sass = require('gulp-sass')(require('sass'));
const browserSync = require('browser-sync').create();

const paths = {
  styles: './app/scss/**/*.scss',
  html: './app/**/*.html',
  scripts: './app/**/*.js',
  dest: './app'
};

function compileSass() {
  return gulp.src(paths.styles)
    .pipe(sass().on('error', sass.logError))
    .pipe(gulp.dest('./app/css'))
    .pipe(browserSync.stream()); // Injects CSS changes without full page reload
}

function watchFiles() {
  browserSync.init({
    server: {
      baseDir: paths.dest
    },
    // Optional: if you have an existing backend server
    // proxy: "http://localhost:8000",
    // port: 3000, // Default port for BrowserSync UI
    open: false // Don't open a new browser window automatically
  });

  gulp.watch(paths.styles, compileSass);
  gulp.watch(paths.html).on('change', browserSync.reload);
  gulp.watch(paths.scripts).on('change', browserSync.reload);
}

// Define default task
exports.default = gulp.series(compileSass, watchFiles);