connect-browser-sync

2.1.0 verified Sat Apr 25 auth: no javascript maintenance

Connect middleware that automatically injects BrowserSync script tags into responses. Version 2.1.0 supports BrowserSync >=2.0.0, with an optional Turbolinks workaround. Released 2015, no recent updates. Compared to Gulp/Grunt plugins, this integrates directly with Connect/Express middleware stack.

Common errors

error ReferenceError: bs is not defined ↓

cause Middleware is called with undefined bs variable.

fix

var bs = browserSync.create().init({ logSnippet: false }); app.use(require('connect-browser-sync')(bs));

error TypeError: connect-browser-sync is not a function ↓

cause Missing parentheses: not calling the factory.

fix

app.use(require('connect-browser-sync')(bs));

error BrowserSync script tag not injected ↓

cause Middleware not executed because it's placed after route handlers, or response is not text/html.

fix

Move middleware before all routes. Check Content-Type header.

error Cannot find module 'browser-sync' ↓

cause browser-sync is not installed.

fix

npm install browser-sync --save-dev

Warnings

gotcha Middleware must be placed before any route/static handlers you want BrowserSync to affect. ↓

fix Ensure app.use(require('connect-browser-sync')(bs)) appears before app.use(express.static(...)) and route definitions.

breaking Version 2.x only works with browser-sync >=2.0.0. Version 1.x uses browser-sync 1.x. ↓

fix Upgrade both packages: npm install browser-sync@latest connect-browser-sync@latest

deprecated Package not updated since 2015, and BrowserSync has evolved. May still work but consider modern alternatives like Vite or webpack HMR. ↓

fix Evaluate if package is still functional with your BrowserSync version; test thoroughly.

gotcha Injection only works on responses with Content-Type: text/html and containing </body> or </head>. Non-HTML responses are ignored. ↓

fix Ensure your HTML responses have proper doctype and closing body/head tags.

gotcha When using Turbolinks, set { injectHead: true } to avoid conflicts. ↓

fix Pass second argument: app.use(require('connect-browser-sync')(bs, { injectHead: true }));

Install

npm install connect-browser-sync

yarn add connect-browser-sync

pnpm add connect-browser-sync

Imports

connect-browser-sync

wrong

import { connectBrowserSync } from 'connect-browser-sync';

correct

var connectBrowserSync = require('connect-browser-sync');

CommonJS only; no default or named ESM export. Use require().

browser-sync
wrong
```
var bs = require('browser-sync').init({...});
```
correct
```
var browserSync = require('browser-sync').create();
```
Must call .create() and then .init() on the instance. .init() returns the instance.
middleware invocation
wrong
```
app.use(require('connect-browser-sync'));
```
correct
```
app.use(require('connect-browser-sync')(bs));
```
The middleware factory expects a BrowserSync instance. Do not pass the raw module.

Quickstart

Shows how to set up connect-browser-sync with Express in development mode, injecting BrowserSync scripts.

var express = require('express');
var app = express();

if (app.get('env') === 'development') {
  var browserSync = require('browser-sync');
  var bs = browserSync.create().init({ logSnippet: false });
  app.use(require('connect-browser-sync')(bs));
  app.get('/hello', function(req, res) {
    res.send('<html><body>Hello</body></html>');
  });
  app.listen(3000);
}