Registry / devops / browser-sync-client

browser-sync-client

JSON →
library3.0.4jsnpmunverified

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.

devops
npm install browser-sync-client
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · BROWSER-SYNC-CLIEN
B
browser-sync-client
devopsjavascriptv3.0.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

browser-sync-client script injection
✓ <!-- No direct import needed; BrowserSync server injects this script --> <script async src='http://HOST:3000/browser-sync/browser-sync-client.js?v=VERSION'></script>
✗ import 'browser-sync-client';
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
✓ import browserSync from 'browser-sync'; // ... then use browserSync.reload() or other API calls
✗ import { client } from 'browser-sync-client';
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.

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);
Debug
Known issues
gotchaThe `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.
affects: >=1.0.0
breakingWhen 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.
affects: >=2.0.0
gotchaOn 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`.
affects: >=1.0.0
deprecatedThe `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.
affects: >=3.0.0
Errors
Common errors & fixes
Error: `node-gyp` failed to compile native addon. See the npm log for details.
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`.
TypeError: Cannot read properties of undefined (reading 'local')
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'])`.
BrowserSync not connecting (no 'Connected to BrowserSync' notification)
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.
Upgrade
Version history
3.0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
4
Resources
githubhttps://github.com/shakyshane/browser-sync-client ↗
packagehttps://www.npmjs.com/package/browser-sync-client ↗
homepagehttps://browsersync.io ↗
browser-sync-client — npm install browser-sync-client · libregistry