ZetCode

Gulp Browsersync

last modified November 15, 2026

In this article we set up Browsersync with Gulp 5. Browsersync runs a local development server, injects changed CSS into the page without reloading it, reloads the page when HTML changes, and can proxy an existing backend. We build a small example and check what the server sends to the browser.

Browsersync

Browsersync is a development server for front-end work. It serves static files, or sits in front of a dynamic server as a proxy, and inserts a small client script into every HTML page it delivers. The script keeps a connection to the server. When the build tells Browsersync about a change, the server asks every connected browser to react: a changed stylesheet is swapped in place, anything else triggers a page reload. The same page can be open in several browsers and on several devices, and they all update together.

Browsersync does not watch files for Gulp tasks; it only talks to browsers. In a Gulp project the Gulp watch function detects the change, a task rebuilds the output, and the task or the watcher then calls Browsersync.

Installing the project

We create the project and install Gulp, browser-sync, and gulp-clean-css. The sources of the stylesheet are in src/css, and the server serves the public directory.

$ mkdir gulp-browsersync
$ cd gulp-browsersync
$ npm init -y
$ npm i -D gulp browser-sync gulp-clean-css
$ mkdir -p src/css public/css

The page

The page is minimal: a heading and a link to the stylesheet that the Gulp task generates.

public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Browsersync demo</title>
    <link rel="stylesheet" href="css/site.css">
</head>
<body>
    <h1>Hello, Browsersync</h1>
</body>
</html>

The page loads css/site.css, which is produced from the source file below by minification.

src/css/site.css
body {
    font-family: sans-serif;
    color: #333333;
}

The source stylesheet sets the font and colour of the text.

The gulpfile

The gulpfile has two tasks, styles and serve, and the default task runs them in series.

gulpfile.mjs
import { src, dest, watch, series } from 'gulp';
import cleanCSS from 'gulp-clean-css';
import browserSync from 'browser-sync';

const server = browserSync.create();

function styles() {

    return src('src/css/*.css')
        .pipe(cleanCSS())
        .pipe(dest('public/css'))
        .pipe(server.stream());
}

function serve(done) {

    server.init({
        server: 'public',
        open: false,
        notify: false,
        ui: false
    });

    watch('src/css/*.css', styles);
    watch('public/*.html').on('change', server.reload);

    done();
}

export default series(styles, serve);

We go through the file piece by piece.

const server = browserSync.create();

The create method returns a named server instance. Using an instance instead of the default one keeps the code clean and allows several servers in one project.

server.init({
    server: 'public',
    open: false,
    notify: false,
    ui: false
});

The server option is the directory to serve. By default Browsersync opens a browser tab at startup, shows a small notification in the page when it reloads, and starts a control panel on another port. The three options we pass turn these features off; the page opens when we visit the address ourselves.

return src('src/css/*.css')
    .pipe(cleanCSS())
    .pipe(dest('public/css'))
    .pipe(server.stream());

The stream method returns a stream that passes the files through and, for each written CSS file, tells the browsers to refresh just that stylesheet. The page is not reloaded and keeps its state, such as the scroll position and the contents of the forms. Other kinds of files, such as scripts, cannot be injected and need a full reload.

watch('src/css/*.css', styles);
watch('public/*.html').on('change', server.reload);

The first watcher rebuilds the styles. The second one calls server.reload whenever an HTML file changes, because HTML cannot be injected. The serve task calls done after the server is started to tell Gulp that the task is finished; the open server and the watchers keep the process running.

Running the server

We start the default task. Browsersync prints the local address and an external address that devices in the same network can use. Then we append a rule to the stylesheet and edit the heading of the HTML file. The CSS change is reported as a changed file that is injected, and the HTML change makes Browsersync reload the browsers. No browser is connected in this transcript; if you open the local address in one, the page appears, a CSS edit changes its look without a reload, and an HTML edit reloads it.

$ npx gulp
[12:45:52] Using gulpfile ~/Documents/prog/js/gulp-browsersync/gulpfile.mjs
[12:45:52] Starting 'default'...
[12:45:52] Starting 'styles'...
[12:45:52] Finished 'styles' after 19 ms
[12:45:52] Starting 'serve'...
[12:45:52] Finished 'serve' after 9.03 ms
[12:45:52] Finished 'default' after 30 ms
[Browsersync] Access URLs:
 -----------------------------------
    Local: http://localhost:3000
 External: http://192.168.1.199:3000
 -----------------------------------
[Browsersync] Serving files from: public
[12:45:54] Starting 'styles'...
[Browsersync] 1 file changed (site.css)
[12:45:54] Finished 'styles' after 9.08 ms
[Browsersync] Reloading Browsers...

The injected script

To see what the server sends, we request the page with curl while the server runs. Browsersync inserts its client only into responses to requests that accept HTML, so we send the Accept header like a browser does. The response is the original page with a script element added directly after the opening body tag. The script appends the Browsersync client, loaded from the server itself, to the page. The client then connects to the server and waits for commands.

$ curl -s -H 'Accept: text/html' localhost:3000/
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Browsersync demo</title>
    <link rel="stylesheet" href="css/site.css">
</head>
<body><script id="__bs_script__">//<![CDATA[
  (function() {
    try {
      var script = document.createElement('script');
      if ('async') {
        script.async = true;
      }
      script.src = '/browser-sync/browser-sync-client.js?v=3.0.4'.replace("HOST", location
      if (document.body) {
        document.body.appendChild(script);
      } else if (document.head) {
        document.head.appendChild(script);
      }
    } catch (e) {
      console.error("Browsersync: could not append script tag", e);
    }
  })()
//]]></script>

    <h1>Hello, Browsersync</h1>
</body>
</html>

Proxy mode

When the pages come from an application server, such as a PHP, Django, or Node.js application, there are no static files for Browsersync to serve. The proxy option makes it forward every request to the application and inject the client script into the HTML responses on the way back. Nothing has to change in the application.

For a test we need a backend. This small Node.js server answers every request with a HTML page.

backend.mjs
import { createServer } from 'node:http';

const page = `<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>Backend</title></head>
<body><h1>Rendered by the backend</h1></body>
</html>
`;

createServer((req, res) => {

    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
    res.end(page);

}).listen(8080, () => console.log('backend on http://localhost:8080'));

The gulpfile for the proxy mode needs no static server and no styles. It starts Browsersync with the address of the backend and reloads the browsers when an HTML file in the project changes; the same pattern works for templates in a real application.

proxy.mjs
import { watch } from 'gulp';
import browserSync from 'browser-sync';

export function proxy(done) {

    const server = browserSync.create();

    server.init({
        proxy: 'localhost:8080',
        open: false,
        notify: false,
        ui: false
    });

    watch('*.html').on('change', server.reload);
    done();
}

We start the backend and the proxy and request the page from the proxy, on port 3000. The response comes from the backend, with the Browsersync script inserted. On Node.js 22 the proxy mode also prints a deprecation warning, which is raised by an old dependency of Browsersync and can be ignored.

$ node backend.mjs &
$ npx gulp --gulpfile proxy.mjs proxy
[12:46:16] Using gulpfile ~/Documents/prog/js/gulp-browsersync/proxy.mjs
[12:46:16] Starting 'proxy'...
[12:46:16] Finished 'proxy' after 15 ms
[Browsersync] Proxying: http://localhost:8080
[Browsersync] Access URLs:
 -----------------------------------
    Local: http://localhost:3000
 External: http://192.168.1.199:3000
 -----------------------------------
(node:34879) [DEP0060] DeprecationWarning: The `util._extend` API is deprecated. Please use Object.assign() instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
$ curl -s -H 'Accept: text/html' localhost:3000/ | tail -4
  })()
//]]></script>
<h1>Rendered by the backend</h1></body>
</html>

Source

Browsersync with Gulp, Browsersync options, browser-sync on npm

In this article we have used Browsersync with Gulp 5: a static server with CSS injection and reloads, the injected client script, and proxy mode for existing backends. See also the Gulp watch and Gulp Sass tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.