Drupal 8 + Gulp + BrowserSync

You might wonder whether you need automation task runners like Grunt or Gulp with Drupal. Common usecases for these tools are css/js aggregation/minification but these are already handled well by Drupal, or if you need more control by modules like Advanced CSS/JSS aggregation.

There are however at least two ways in which a task runner can help you out: frontend testing and "livereload". I won't be covering frontend testing here, that's something for another post, but it's worth mentioning because it is comething which is currently often lacking in Drupal project. Note: there is an attempt in this issue to bring frontend testing into drupal core using behat/phantomjs.

Browser syncing
Browsersyncing will inject newly created CSS (compiled from Sass) into your browser without the need for a hard page refresh. This saves a lot of time, especially on pages which needs a lot of clicking to get to the right elements.

Here is the setup:

Install nodejs on your system, follow the instructions based on your OS.

Install Gulp globally:

npm install --global gulp

Or goto your theme folder and install everything locally:

npm install gulp gulp-sass browser-sync

This will install gulp and 2 plugins: gulp-sass and browsersync. This will also create a node_modules folder in your theme dir.

Note: until this core patch lands in core, make sure to apply it to prevent localhost errors on flush cache all.

Note: gulp-sass uses libsass which is *a lot* faster than ruby-sass. If you are using phpstorm with a compass watcher, you can now disable that for your projects.

Next, create a gulpfile.js in your theme folder and edit the following code. You might need to replace folder names according to your own.

var gulp        = require('gulp');
var browserSync = require('browser-sync').create();
var sass        = require('gulp-sass');
// sassOptions are optional but things like sourceComments (line_comments) can be pretty handy.
var sassOptions = {
    errLogToConsole: true,
    outputStyle: 'expanded',
    sourceComments: 'normal'
// Defining our 'serve' task which is called at the end.
gulp.task('serve', ['sass'], function() {
    // if you are using a VM or something like MAMP you will want to use a proxy:
        proxy: 'http://my-site.localhost'
    // Note the /*/ which means we will also watch subfolders, useful for mixins/extends.
    gulp.watch("sass/*/*.scss", ['sass']);
    gulp.watch("scripts/*.js").on('change', browserSync.reload);
// Compile sass into CSS & auto-inject into browsers
gulp.task('sass', function() {
    return gulp.src("sass/*.scss")
        .pipe(sass(sassOptions).on('error', sass.logError))
        .pipe(browserSync.reload({ stream: true })) // this is where the magic happens
gulp.task('default', ['serve']);

What this javascript basically does is: define two tasks ('serve' and 'sass'). When gulp starts, serve will be called which in turn watches your *.scss files. If there is a change, it will call the sass task which compiles it to css and inject the css to your browser. If there is a *.js change, it will do a hard refresh.

Next, install browsersync module. For a normal non-drupal project this might be sufficient, but for Drupal we will need this additonal module for two reasons: 

  1. browsersync needs an additional javacsript embedded at the end of your page to make it work with a proxy setup
  2. Style sheets need to embedded with the <link> tag instead of @import. Drupal 7 & 8 use @import when aggregation is turned off in order to workaround the limitations for including a maximal numer of CSS files up to IE9, but we won't be needing that anymore.

Follow the instructions for enabling and activing this module:

  • dont' forget to set the permissions or else browsersync will only work if logged in (as root).
  • activate browsersync per theme in your theme settings

Note: there is a functional release for Drupal 8 of this module in this issue.

Last, you will need to fire up Gulp by starting it using the command below, executed from the theme folder:


This command will fire up a browser tab which will read localhost:3000 but it will show the site you defined in your gulpfile as proxy. You should briefly see "Connected to BrowserSync" in the upper right corner. Now, try edditing and saving a sass file.

Note: as a bonus you get the BrowserSync UI which has some nice goodies. Watch your console after you startup Gulp for the URL.

Grunt vs Gulp
I focussed on Gulp in this post because I think it's a better fit for Drupal: it seems enforce less and be more flexible and I'm more familiar with it, but It's probably possible to achieve the same goals with Grunt.

Next Generation Web Apps using the Service Worker

Read More »


This is the company blog of
Drupal specialist Merge.nl

We are located in Breda (Netherlands) and build websites using Drupal. More about us.

Content on this blog is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Netherlands License.

Creative Commons License

Recent Comments