Using ES6 in your Drupal Components

If you’ve read my post about the Asset Library system you’ll know we’re big fans of the Component-Driven Design approach, and having a javascript file per component (where needed of course) is ideal. We also like to keep our JS widgets generic so that the entire component (entire styleguide for that matter) can be used outside of Drupal as well. Drupal behaviours and settings are still used but live in a different javascript file to the generic widget, and simply call it’s function, passing in Drupal settings as “options” as required.

Here is an example with an ES5 jQuery header component, with a breakpoint value set somewhere in Drupal:

@file header.js

(function ($) {

 // Overridable defaults
 $.fn.header.defaults = {
   breakpoint: 700,
   toggleClass: 'header__toggle',
   toggleClassActive: 'is-active'
 };

 $.fn.header = function (options) {
   var opts = $.extend({}, $.fn.header.defaults, options);
   return this.each(function () {
     var $header = $(this);
     // do stuff with $header
  }

})(jQuery);

@file header.drupal.js

(function ($, Drupal, drupalSettings) {
 Drupal.behaviors.header = {
   attach: function (context) {
     $('.header', context).header({
       breakpoint: drupalSettings.my_theme.header.breakpoint
     });
   }
 };
})(jQuery, Drupal, drupalSettings);

Converting these files into a different language is relatively simple as you can do one at a time and slowly chip away at the full set. Since ES6 is used in the popular JS frameworks it’s a good starting point for slowly moving towards a “progressively decoupled” front-end.

Support for ES6

Before going too far I should mention support for this syntax isn’t quite widespread enough yet! No fear though, we just need to add a “transpiler” into our build tools. We use Babel, with the babel-preset-env, which will convert our JS for us back into ES5 so that the required older browsers can still understand it.

Our Gulp setup will transpile any .es6.js file and rename it (so we’re not replacing our working file), before passing the renamed file into out minifying Gulp task.

With the Babel ENV preset we can specify which browsers we actually need to support, so that we’re doing the absolute minimum transpilation (is that a word?) and keeping the output as small as possible. There’s no need to bloat your JS trying to support browsers you don’t need to!

import gulp from 'gulp';
import babel from 'gulp-babel';
import path from 'path';
import config from './config';

// Helper function for renaming files
const bundleName = (file) => {
 file.dirname = file.dirname.replace(/\/src$/, '');
 file.basename = file.basename.replace('.es6', '');
 file.extname = '.bundle.js';
 return file;
};

const transpileFiles = [
 `${config.js.src}/**/*.js`,
 `${config.js.modules}/**/*.js`,
 // Ignore already minified files.
 `!${config.js.src}/**/*.min.js`,
 `!${config.js.modules}/**/*.min.js`,
 // Ignore bundle files, so we don’t transpile them twice (will make more sense later)
 `!${config.js.src}/**/src/*.js`,
 `!${config.js.modules}/**/src/*.js`,
 `!${config.js.src}/**/*.bundle.js`,
 `!${config.js.modules}/**/*.bundle.js`,
];

const transpile = () => (
 gulp.src(transpileFiles, { base: './' })
   .pipe(babel({
     presets: [['env', {
       modules: false,
       useBuiltIns: true,
       targets: { browsers: ["last 2 versions", "> 1%"] },
     }]],
   }))
   .pipe(rename(file => (bundleName(file))))
   .pipe(gulp.dest('./'))
);

transpile.description = 'Transpile javascript.';
gulp.task('scripts:transpile', transpile);

Which uses:

$ yarn add path gulp gulp-babel babel-preset-env --dev

On a side note, we’ll be outsourcing our entire Gulp workflow real soon. We’re just working through a few extra use cases for it, so keep an eye out!

Learning ES6

Reading about ES6 is one thing but I find getting into the code to be the best way for me to learn things. We like to follow Drupal coding standards so point our eslint config to extend what’s in Drupal core. Upgrading to 8.4.x obviously threw a LOT of new lint errors, and was usually disabled until time permitted their correction. But you can use these errors as a tailored ES6 guide. Tailored because it’s directly applicable to how you usually write JS (assuming you wrote the first code).

Working through each error, looking up the description, correcting it manually (as opposed to using the --fix flag) was a great way to learn it. It took some time, but once you understand a rule you can start skipping it, then use the --fix flag at the end for a bulk correction.

Of course you're also a Google away from a tonne of online resources and videos to help you learn if you prefer that approach!

ES6 with jQuery

Our original code is usually in jQuery, and I didn’t want to add removing jQuery into the refactor work, so currently we’re using both which works fine. Removing it from the mix entirely will be a future task.

The biggest gotcha was probably our use of this, once converted to arrow functions needed to be reviewed. Taking our header example from above:

return this.each(function () { var $header = $(this); }

Once converted into an arrow function, using this inside the loop is no longer scoped to the function. It doesn’t change at all - it’s not an individual element of the loop anymore, it’s still the same object we’re looping through. So clearly stating the obj as an argument of the .each() function lets us access the individual element again.

return this.each((i, obj) => { const $header = $(obj); }

Converting the jQuery plugins (or jQuery UI widgets) to ES6 modules was a relatively easy task as well… instead of:

(function ($) {

 // Overridable defaults
 $.fn.header.defaults = {
   breakpoint: 700,
   toggleClass: 'header__toggle',
   toggleClassActive: 'is-active'
 };

 $.fn.header = function (options) {
   var opts = $.extend({}, $.fn.header.defaults, options);
   return this.each(function () {
     var $header = $(this);
     // do stuff with $header
  }

})(jQuery);

We just make it a normal-ish function:

const headerDefaults = {
 breakpoint: 700,
 toggleClass: 'header__toggle',
 toggleClassActive: 'is-active'
};

function header(options) {
 (($, this) => {
   const opts = $.extend({}, headerDefaults, options);
   return $(this).each((i, obj) => {
     const $header = $(obj);
     // do stuff with $header
   });
 })(jQuery, this);
}

export { header as myHeader }

Since the exported ES6 module has to be a top level function, the jQuery wrapper was moved inside it, along with passing through the this object. There might be a nicer way to do this but I haven't worked it out yet! Everything inside the module is the same as I had in the jQuery plugin, just updated to the new syntax.

I also like to rename my modules when I export them so they’re name-spaced based on the project, which helps when using a mix of custom and vendor scripts. But that’s entirely optional.

Now that we have our generic JS using ES6 modules it’s even easier to share and reuse them. Remember our Drupal JS separation? We no longer need to load both files into our theme. We can import our ES6 module into our .drupal.js file then attach it as a Drupal behaviour. 

@file header.drupal.js

import { myHeader } from './header';

(($, { behaviors }, { my_theme }) => {
 behaviors.header = {
   attach(context) {
     myHeader.call($('.header', context), {
       breakpoint: my_theme.header.breakpoint
     });
   }
 };
})(jQuery, Drupal, drupalSettings);

So a few differences here, we're importing the myHeader function from our other file,  we're destructuring our Drupal and drupalSettings arguments to simplify them, and using .call() on the function to pass in the object before setting its arguments. Now the header.drupal.js file is the only file we need to tell Drupal about.

Some other nice additions in ES6 that have less to do with jQuery are template literals (being able to say $(`.${opts.toggleClass}`) instead of $('.' + opts.toggleClass')) and the more obvious use of const and let instead of var , which are block-scoped.

Importing modules into different files requires an extra step in our build tools, though. Because browser support for ES6 modules is also a bit too low, we need to “bundle” the modules together into one file. The most popular bundler available is Webpack, so let’s look at that first.

Bundling with Webpack

Webpack is super powerful and was my first choice when I reached this step. But it’s not really designed for this component based approach. Few of them are truly... Bundlers are great for taking one entry JS file which has multiple ES6 modules imported into it. Those modules might be broken down into smaller ES6 modules and at some level are components much like ours, but ultimately they end up being bundled into ONE file.

But that’s not what I wanted! What I wanted, as it turned out, wasn’t very common. I wanted to add Webpack into my Gulp tasks much like our Sass compilation is, taking a “glob” of JS files from various folders (which I don’t really want to have to list), then to create a .bundle.js file for EACH component which included any ES6 modules I used in those components.

The each part was the real clincher. Getting multiple entry points into Webpack is one thing, but multiple destination points as well was certainly a challenge. The vinyl-named npm module was a lifesaver. This is what my Gulp talk looked like:

import gulp from 'gulp';
import gulp-webpack from 'webpack-stream';
import webpack from 'webpack'; // Use newer webpack than webpack-stream
import named from 'vinyl-named';
import path from 'path';
import config from './config';

const bundleFiles = [
 config.js.src + '/**/src/*.js',
 config.js.modules + '/**/src/*.js',
];

const bundle = () => (
 gulp.src(bundleFiles, { base: "./" })
   // Define [name] with the path, via vinyl-named.
   .pipe(named((file) => {
     const thisFile = bundleName(file); // Reuse our naming helper function
     // Set named value and queue.
     thisFile.named = thisFile.basename;
     this.queue(thisFile);
   }))
   // Run through webpack with the babel loader for transpiling to ES5.
   .pipe(gulp-webpack({
     output: {
       filename: '[name].bundle.js', // Filename includes path to keep directories
     },
     module: {
       loaders: [{
         test: /\.js$/,
         exclude: /node_modules/,
         loader: 'babel-loader',
         query: {
           presets: [['env', { 
             modules: false, 
             useBuiltIns: true, 
             targets: { browsers: ["last 2 versions", "> 1%"] }, 
           }]],
         },
       }],
     },
   }, webpack))
   .pipe(gulp.dest('./')) // Output each [name].bundle.js file next to it’s source
);

bundle.description = 'Bundle ES6 modules.';
gulp.task('scripts:bundle', bundle);

Which required:

$ yarn add path webpack webpack-stream babel-loader babel-preset-env vinyl-named --dev

This worked. But Webpack has some boilerplate JS that it adds to its bundle output file, which it needs for module wrapping etc. This is totally fine when the output is a single file, but adding this (exact same) overhead to each of our component JS files, it starts to add up. Especially when we have multiple component JS files loading on the same page, duplicating that code.

It only made each component a couple of KB bigger (once minified, an unminified Webpack bundle is much bigger), but the site seemed so much slower. And it wasn’t just us, a whole bunch of our javascript tests started failing because the timeouts we’d set weren’t being met. Comparing the page speed to the non-webpack version showed a definite impact on performance.

So what are the alternatives? Browserify is probably the second most popular but didn’t have the same ES6 module import support. Rollup.js is kind of the new bundler on the block and was recommended to me as a possible solution. Looking into it, it did indeed sound like the lean bundler I needed. So I jumped ship!

Bundling with Rollup.js

The setup was very similar so it wasn’t hard to switch over. It had a similar problem about single entry/destination points but it was much easier to resolve with the ‘gulp-rollup-each’ npm module. My Gulp task now looks like:

import gulp from 'gulp';
import rollup from 'gulp-rollup-each';
import babel from 'rollup-plugin-babel';
import resolve from 'rollup-plugin-node-resolve';
import commonjs from 'rollup-plugin-commonjs';
import path from 'path';
import config from './config';

const bundleFiles = [
 config.js.src + '/**/src/*.js',
 config.js.modules + '/**/src/*.js',
];

const bundle = () => {
 return gulp.src(bundleFiles, { base: "./" })
   .pipe(rollup({
     plugins: [
       resolve(),
       commonjs(),
       babel({
         presets: [['env', {
           modules: false,
           useBuiltIns: true,
           targets: { browsers: ["last 2 versions", "> 1%"] },
         }]],
         babelrc: false,
         plugins: ['external-helpers'],
       })
     ]
   }, (file) => {
     const thisFile = bundleName(file); // Reuse our naming helper function
     return {
       format: 'umd',
       name: path.basename(thisFile.path),
     };
   }))
   .pipe(gulp.dest('./')); // Output each [name].bundle.js file next to it’s source
};

bundle.description = 'Bundle ES6 modules.';
gulp.task('scripts:bundle', bundle);

We don’t need vinyl-named to rename the file anymore, we can do that as a callback of gulp-rollup-each. But we need a couple of extra plugins to correctly resolve npm module paths.

So for this we needed:

$ yarn add path gulp-rollup-each rollup-plugin-babel babel-preset-env rollup-plugin-node-resolve rollup-plugin-commonjs --dev

Rollup.js does still add a little bit of boilerplate JS but it’s a much more acceptable amount. Our JS tests all passed so that was a great sign. Page speed tests showed the slight improvement I was expecting, having bundled a few files together. We're still keeping the original transpile Gulp task too for ES6 files that don't include any imports, since they don't need to go through Rollup.js at all.

Webpack might still be the better option for more advanced things that a decoupled frontend might need, like Hot Module Replacement. But for simple or only slightly decoupled components Rollup.js is my pick.

Next steps

Some modern browsers can already support ES6 module imports, so this whole bundle step is becoming somewhat redundant. Ideally the bundled file with it’s overhead and old fashioned code is only used on those older browsers that can’t handle the new and improved syntax, and the modern browsers use straight ES6...

Luckily this is possible with a couple of script attributes. Our .bundle.js file can be included with the nomodule attribute, alongside the source ES6 file with a type=”module” attribute. Older browsers ignore the type=module file entirely because modules aren’t supported and browsers that can support modules ignore the ‘nomodule’ file because it told them to. This article explains it more.

Then we'll start replacing the jQuery entirely, even look at introducing a Javascript framework like React or Glimmer.js to the more interactive components to progressively decouple our front-ends!