gulp.hbs

---
layout: "documentation.hbs"
title: "Browsersync + Gulp.js"
page-label: "gulp"
sidebar: "gulp-sidebar.hbs"
markdown: false
---

{{#md}}
There's no official Browsersync plugin for Gulp, because it's not needed! You simply `require` the module, utilise
the [API]({{site.links.api}}) and configure it with [options]({{site.links.options}}). The following are some common
use-cases as seen in popular projects such as [Google's web starter kit](https://developers.google.com/web/starter-kit/)
and many others.
{{/md}}

{{ inc src="headerlink.html" title="Install" slug="gulp-install" }}

{{#md}}
First, you'll need to install Browsersync & Gulp as development dependencies.
{{/md}}

{{ hl src="snippets/gulp/install.txt" lang="html" }}

{{#md}}
Then, use them within your `gulpfile.js`:
{{/md}}

{{ hl src="snippets/gulp/require.js" }}

{{ inc src="headerlink.html" title="SASS + CSS Injecting" slug="gulp-sass-css" }}

{{#md}}
Streams are supported in Browsersync, so you can call reload at specific points during your tasks and
all browsers will be informed of the changes. Because Browsersync only cares about your CSS when it's
*finished* compiling - make sure you call `.stream()` *after* `gulp.dest`
{{/md}}

{{ hl src="snippets/gulp/sass.js" }}

{{ inc src="headerlink.html" title="Ruby SASS & Source Maps" slug="gulp-sass-maps" }}

{{#md}}
If you use [gulp-ruby-sass](https://www.npmjs.org/package/gulp-ruby-sass) with the `sourcemap: true` option, additional `.map`
files will be generated. These files end up being sent down stream and when `browserSync.reload()` receives them, it will attempt
a full page reload (as it will not find any `.map` files in the DOM).

To fix this problem, use `browserSync.stream({match: '**/*.css'})` as seen in the following example.
{{/md}}

{{ hl src="snippets/gulp/sass.maps.js" }}

{{ inc src="headerlink.html" title="Browser Reloading" slug="gulp-reload" }}

{{#md}}
Sometimes you might just want to reload the page completely (for example, after processing a bunch of JS files), but
you want the reload to happen *after* your tasks. This will be easier in gulp `4.x.x`, but for now you can do the following
(make sure you `return` the stream from your tasks to ensure that `browserSync.reload()` is called at the correct time).

If you are using gulp `4.x.x` now, then you can [follow this documentation](https://github.com/gulpjs/gulp/blob/master/docs/recipes/minimal-browsersync-setup-with-gulp4.md).
{{/md}}

{{ hl src="snippets/gulp/reload.js" }}

{{ inc src="headerlink.html" title="Manual Reloading" slug="gulp-manual-reload" }}

{{#md}}
If the streams support doesn't suit your needs, you can fire the reload method manually
by wrapping it in a task. This example will compile & auto-inject CSS just as before, but when HTML files are
changed, the browsers will be reloaded instead.
{{/md}}

{{ hl src="snippets/gulp/reload.manual.js" }}