{"id":17519,"library":"browser-sync-client","title":"BrowserSync Client-Side Script","description":"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.","status":"maintenance","version":"3.0.4","language":"javascript","source_language":"en","source_url":"git://github.com/shakyshane/browser-sync-client","tags":["javascript"],"install":[{"cmd":"npm install browser-sync-client","lang":"bash","label":"npm"},{"cmd":"yarn add browser-sync-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add browser-sync-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import 'browser-sync-client';","symbol":"browser-sync-client script injection","correct":"<!-- No direct import needed; BrowserSync server injects this script -->\n<script async src='http://HOST:3000/browser-sync/browser-sync-client.js?v=VERSION'></script>"},{"note":"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.","wrong":"import { client } from 'browser-sync-client';","symbol":"BrowserSync instance for control","correct":"import browserSync from 'browser-sync';\n// ... then use browserSync.reload() or other API calls"}],"quickstart":{"code":"const gulp = require('gulp');\nconst sass = require('gulp-sass')(require('sass'));\nconst browserSync = require('browser-sync').create();\n\nconst paths = {\n  styles: './app/scss/**/*.scss',\n  html: './app/**/*.html',\n  scripts: './app/**/*.js',\n  dest: './app'\n};\n\nfunction compileSass() {\n  return gulp.src(paths.styles)\n    .pipe(sass().on('error', sass.logError))\n    .pipe(gulp.dest('./app/css'))\n    .pipe(browserSync.stream()); // Injects CSS changes without full page reload\n}\n\nfunction watchFiles() {\n  browserSync.init({\n    server: {\n      baseDir: paths.dest\n    },\n    // Optional: if you have an existing backend server\n    // proxy: \"http://localhost:8000\",\n    // port: 3000, // Default port for BrowserSync UI\n    open: false // Don't open a new browser window automatically\n  });\n\n  gulp.watch(paths.styles, compileSass);\n  gulp.watch(paths.html).on('change', browserSync.reload);\n  gulp.watch(paths.scripts).on('change', browserSync.reload);\n}\n\n// Define default task\nexports.default = gulp.series(compileSass, watchFiles);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`.","cause":"Missing Visual C++ build tools on Windows required by native dependencies of BrowserSync.","error":"Error: `node-gyp` failed to compile native addon. See the npm log for details."},{"fix":"Update your code to use the `getIn` method for accessing options: `bs.options.getIn(['urls', '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.","error":"TypeError: Cannot read properties of undefined (reading 'local')"},{"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.","cause":"The client script failed to inject, a firewall is blocking the connection, or an incorrect host/port is configured.","error":"BrowserSync not connecting (no 'Connected to BrowserSync' notification)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}