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.
<!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.
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.
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.
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.
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
List all Gulp tutorials.