├── .gitignore ├── README.md ├── README.old.md ├── gulpfile-example-01.js ├── gulpfile-example-API.js ├── gulpfile-example-proxy.js ├── gulpfile-example-reloading-after-tasks.js └── gulpfile-example-server.js /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .idea 3 | npm-debug.log 4 | .sass-cache -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Browsersync + Gulp 2 | 3 | > How to use the [Browsersync](https://github.com/shakyShane/browser-sync) module with gulp. 4 | 5 | Follow [@browserSync](http://www.twitter.com/browserSync) for news & updates. 6 | 7 | ## About 8 | 9 | For a full list of features, please visit [https://github.com/shakyShane/browser-sync](https://github.com/shakyShane/browser-sync) 10 | 11 | ## Usage 12 | 13 | Please see the official [Browsersync + Gulp Documentation](http://www.browsersync.io/docs/gulp/) for details. (if you want to see the old examples, 14 | which may no longer be supported, checkout the readme.old.md file) 15 | 16 | ## Support 17 | If you've found Browsersync to be useful and would like to contribute to its continued development & support, please feel free to send a donation of any size - it would be greatly appreciated! 18 | 19 | [![Support via Gittip](https://rawgithub.com/chris---/Donation-Badges/master/gittip.jpeg)](https://www.gittip.com/shakyshane) 20 | [![Support via PayPal](https://rawgithub.com/chris---/Donation-Badges/master/paypal.jpeg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=shakyshane%40gmail%2ecom&lc=US&item_name=browser%2dsync) 21 | -------------------------------------------------------------------------------- /README.old.md: -------------------------------------------------------------------------------- 1 | # Browser Sync + Gulp 2 | 3 | > How to use the [browser-sync](https://github.com/shakyShane/browser-sync) module with gulp. 4 | 5 | Follow [@browserSync](http://www.twitter.com/browserSync) for news & updates. 6 | 7 | ## About 8 | 9 | For a full list of features, please visit [https://github.com/shakyShane/browser-sync](https://github.com/shakyShane/browser-sync) 10 | 11 | ## Usage 12 | 13 | First, install `browser-sync` as a development dependency: 14 | 15 | ```shell 16 | npm install browser-sync --save-dev 17 | ``` 18 | 19 | Then, use it within `gulpfile.js`: 20 | 21 | ```js 22 | var gulp = require('gulp'); 23 | var browserSync = require('browser-sync'); 24 | 25 | // Static server 26 | gulp.task('browser-sync', function() { 27 | browserSync.init(null, { 28 | server: { 29 | baseDir: "./" 30 | } 31 | }); 32 | }); 33 | 34 | // or... 35 | 36 | // Proxy to existing vhost (version 0.7.0 & greater) 37 | gulp.task('browser-sync', function() { 38 | browserSync.init(null, { 39 | proxy: "yourlocal.dev" 40 | }); 41 | }); 42 | 43 | // Proxy to existing vhost (before version 0.7.0) * Seriously? time to upgrade. 44 | gulp.task('browser-sync', function() { 45 | browserSync.init(null, { 46 | proxy: { 47 | host: "yourlocal.dev", 48 | port: 80 49 | } 50 | }); 51 | }); 52 | ``` 53 | 54 | There's a [full list of available options](https://github.com/shakyShane/browser-sync/wiki/Working-with-a-Config-File) on the module's repo. 55 | 56 | ## NOTE: at least version 0.8.0 is required for the following examples! ## 57 | 58 | ### Auto reload & CSS injecting 59 | 60 | Streams are now supported in BrowserSync, so you can call `reload` when all your tasks are complete & all browsers will be informed of the changes. 61 | 62 | **Gulp + SASS + CSS Injecting** 63 | 64 | Because BrowserSync only cares about your CSS when it's finished compiling - make sure you call reload *after* `gulp.dest` 65 | 66 | ```js 67 | var gulp = require('gulp'); 68 | var browserSync = require('browser-sync'); 69 | var sass = require('gulp-sass'); 70 | 71 | // browser-sync task for starting the server. 72 | gulp.task('browser-sync', function() { 73 | browserSync.init(null, { 74 | server: { 75 | baseDir: "./" 76 | } 77 | }); 78 | }); 79 | 80 | // Sass task, will run when any SCSS files change & BrowserSync will auto-update browsers 81 | gulp.task('sass', function () { 82 | gulp.src('scss/styles.scss') 83 | .pipe(sass({includePaths: ['scss']})) 84 | .pipe(gulp.dest('css')) 85 | .pipe(browserSync.reload({stream:true})); 86 | }); 87 | 88 | // Default task to be run with `gulp` 89 | gulp.task('default', ['sass', 'browser-sync'], function () { 90 | gulp.watch("scss/*.scss", ['sass']); 91 | }); 92 | ``` 93 | 94 | **SASS & Source Maps** 95 | 96 | If you use [gulp-ruby-sass](https://www.npmjs.org/package/gulp-ruby-sass) with `sourcemap: true` option `*.css.map` file/files will be generated and after css injection browser will be reloaded. To prevent refreshing page after css injection use [gulp-filter](https://www.npmjs.org/package/gulp-filter) package. 97 | 98 | For example: 99 | 100 | ```js 101 | //other necessary packages 102 | var filter = require('gulp-filter'); 103 | 104 | gulp.task('sass', function () { 105 | gulp.src('scss/styles.scss') 106 | .pipe(sass({includePaths: ['scss'], sourcemap: true})) 107 | .pipe(gulp.dest('css')) 108 | .pipe(filter('**/*.css')) // Filtering stream to only css files 109 | .pipe(browserSync.reload({stream:true})); 110 | }); 111 | ``` 112 | 113 | **Browser Reloading** 114 | 115 | Sometimes you might just want to reload the page completely (for example, after processing a bunch of JS files) - you can do that 116 | by passing `once` as an option. This will stop `reload` being call multiple times. 117 | 118 | ```js 119 | // start server 120 | gulp.task('browser-sync', function() { 121 | browserSync.init(null, { 122 | server: { 123 | baseDir: "./" 124 | } 125 | }); 126 | }); 127 | 128 | // process JS files and reload all browsers when complete. 129 | gulp.task('js', function () { 130 | gulp.src('js/*js') 131 | .pipe(browserify()) 132 | .pipe(uglify()) 133 | .pipe(gulp.dest('dist/js')) 134 | .pipe(browserSync.reload({stream:true, once: true})); 135 | }); 136 | 137 | // use default task to lauch BrowserSync and watch JS files 138 | gulp.task('default', ['browser-sync'], function () { 139 | gulp.watch("js/*.js", ['js']); 140 | }); 141 | ``` 142 | 143 | **Reloading manually** 144 | 145 | If the streams support doesn't suit your needs, you can fire the reload method manually by wrapping it in a task. 146 | This example will compile & auto-inject `CSS` just as before, but when `HTML` files are changed, the browsers will be reloaded instead. 147 | 148 | ```js 149 | // Start the server 150 | gulp.task('browser-sync', function() { 151 | browserSync.init(null, { 152 | server: { 153 | baseDir: "./" 154 | } 155 | }); 156 | }); 157 | 158 | // Compile SASS & auto-inject into browsers 159 | gulp.task('sass', function () { 160 | gulp.src('scss/styles.scss') 161 | .pipe(sass({includePaths: ['scss']})) 162 | .pipe(gulp.dest('css')) 163 | .pipe(browserSync.reload({stream:true})); 164 | }); 165 | 166 | // Reload all Browsers 167 | gulp.task('bs-reload', function () { 168 | browserSync.reload(); 169 | }); 170 | 171 | // Watch scss AND html files, doing different things with each. 172 | gulp.task('default', ['browser-sync'], function () { 173 | gulp.watch("scss/*.scss", ['sass']); 174 | gulp.watch("*.html", ['bs-reload']); 175 | }); 176 | ``` 177 | 178 | ### Screencasts 179 | 180 | Coming soon. If you want to see anything specific covered in the screencasts, please ask me [@shaneOsbourne](https://www.twitter.com/shaneosbourne) 181 | 182 | ## Support 183 | 184 | If you've found Browser-sync useful and would like to contribute to its continued development & support, please feel free to send a donation of any size - it would be greatly appreciated! 185 | 186 | [![Support via Gittip](https://rawgithub.com/chris---/Donation-Badges/master/gittip.jpeg)](https://www.gittip.com/shakyshane) 187 | [![Support via PayPal](https://rawgithub.com/chris---/Donation-Badges/master/paypal.jpeg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=shakyshane%40gmail%2ecom&lc=US&item_name=browser%2dsync) 188 | -------------------------------------------------------------------------------- /gulpfile-example-01.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This example: 3 | * Uses the built-in BrowserSync server for HTML files 4 | * Watches & compiles SASS files 5 | * Watches & injects CSS files 6 | */ 7 | var browserSync = require('browser-sync'); 8 | var reload = browserSync.reload; 9 | var gulp = require('gulp'); 10 | var sass = require('gulp-sass'); 11 | var filter = require('gulp-filter'); 12 | 13 | // Browser-sync task, only cares about compiled CSS 14 | gulp.task('browser-sync', function() { 15 | browserSync({ 16 | server: { 17 | baseDir: "./" 18 | } 19 | }); 20 | }); 21 | 22 | // Sass task, will run when any SCSS files change. 23 | gulp.task('sass', function () { 24 | return gulp.src('scss/styles.scss') 25 | .pipe(sass({includePaths: ['scss']})) // compile sass 26 | .pipe(gulp.dest('css')) // write to css dir 27 | .pipe(filter('**/*.css')) // filter the stream to ensure only CSS files passed. 28 | .pipe(reload({stream:true})); // inject into browsers 29 | }); 30 | 31 | // Default task to be run with `gulp` 32 | gulp.task('default', ['sass', 'browser-sync'], function () { 33 | gulp.watch("scss/*.scss", ['sass']); 34 | }); 35 | -------------------------------------------------------------------------------- /gulpfile-example-API.js: -------------------------------------------------------------------------------- 1 | /** 2 | * For the more complex/customised workflows, you may want to handle the file-change 3 | * events manually. This following example is simplistic - but shows how can emit your events 4 | * to BrowserSync whenever you like. 5 | * 6 | * This example: 7 | * Shows how you can emit your own file-change events 8 | */ 9 | 10 | var browserSync = require('browser-sync'); 11 | var reload = browserSync.reload; 12 | var gulp = require('gulp'); 13 | var sass = require('gulp-sass'); 14 | 15 | // This BrowserSync task will start a server, but will NOT watch any files. 16 | gulp.task('browser-sync', function () { 17 | browserSync({ 18 | server: { 19 | baseDir: "./" 20 | } 21 | }); 22 | }); 23 | 24 | // This default task will run BrowserSync & then use Gulp to watch files. 25 | // When a file is changed, an event is emitted to BrowserSync with the filepath. 26 | gulp.task('default', ['browser-sync'], function () { 27 | gulp.watch('css/*.css', function (file) { 28 | if (file.type === "changed") { 29 | reload(file.path); 30 | } 31 | }); 32 | }); 33 | -------------------------------------------------------------------------------- /gulpfile-example-proxy.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This example: 3 | * Shows how to plug in the details of your server. 4 | * Watches & injects CSS files 5 | */ 6 | var gulp = require('gulp'); 7 | var browserSync = require('browser-sync'); 8 | 9 | gulp.task('browser-sync', function() { 10 | browserSync({ 11 | files: "css/*.css", 12 | proxy: "myhost.dev" 13 | }); 14 | }); 15 | 16 | // Default task to be run with `gulp` 17 | gulp.task('default', ["browser-sync"]); 18 | -------------------------------------------------------------------------------- /gulpfile-example-reloading-after-tasks.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This example: 3 | * Launches the BrowserSync server 4 | * Watches & lints JS files 5 | * Reloads the browser after linting has finished. 6 | */ 7 | var browserSync = require('browser-sync'); 8 | var reload = browserSync.reload; 9 | var gulp = require('gulp'); 10 | var jshint = require('gulp-jshint'); 11 | 12 | // Browser-sync task, only cares about compiled CSS 13 | gulp.task('browser-sync', function() { 14 | browserSync({ 15 | server: "./" 16 | }); 17 | }); 18 | 19 | // Lint task. 20 | gulp.task('lint', function () { 21 | gulp.src('js/*.js') 22 | .pipe(jshint()); 23 | }); 24 | 25 | // Default task to be run with `gulp`. 26 | gulp.task('default', ['lint', 'browser-sync'], function () { 27 | gulp.watch('js/*.js', ['lint']).on('change', reload); 28 | }); 29 | -------------------------------------------------------------------------------- /gulpfile-example-server.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This example: 3 | * Shows how to use the built-in server, by default it 4 | * Watches & injects CSS files 5 | */ 6 | var gulp = require('gulp'); 7 | var browserSync = require('browser-sync'); 8 | 9 | gulp.task('browser-sync', function() { 10 | browserSync({ 11 | files: "css/*.css", 12 | server: { 13 | baseDir: "app" // Change this to your web root dir 14 | } 15 | }); 16 | }); 17 | 18 | // Default task to be run with `gulp` 19 | gulp.task('default', ["browser-sync"]); 20 | --------------------------------------------------------------------------------