Modernize Your WordPress JavaScript

Not too long ago, I walked through the basics of using Browserify to organize and improve your JavaScript. Let’s build on that and take it to the next level while smoothly integrating with WordPress’ built-in JavaScript interface.

WordPress Dependencies vs Browserify Requires

While Browserify works great for external libraries, what about libraries included in WordPress core like jQuery or Backbone? You could include them the same as other libraries just using npm and a require statement, but what if there is another script on the same page that requires one of them? The built in scoping of Browserify protects from version conflicts, but it’s still the same library being required twice (or more)!

So how can we solve this? Using an awesome transform for Browserify called browserify-shim. Browserify-shim allows for including external libraries in the exact same way you would with libraries from npm but with a custom location.

You can var $ = require('jquery'); and instead of it loading jQuery from it’s npm package, it will fill it in with the global jQuery variable.

To get it set up, first install:

npm install --save-dev browserify-shim

Add it to your Browserify setup as a transform, in this case using grunt-browserify:

browserify: {
   options: {
     transform: ['browserify-shim']
   },
   dist: { files: { 'assets/js/main.js': 'assets/js/components/main.js' } }
}

And finally configure your shimmed packages in your package.json file.

"browserify-shim": {
   "backbone": "global:Backbone",
   "jquery": "global:jQuery"
},

Now if you or a package you are using requires either of those packages, Browserify will use WordPress’s global versions–as long as you remember to add them to your scripts dependencies in the wp_enqueue_script call, rather than bundling the npm version of the package with the compiled script. This both saves bandwith and integrates better with WordPress.

If you are using any other scripts from WordPress core or elsewhere that you want to shim in as well just add to that section in the package.json file. Place the npm name of the package on the left and “global:” followed by the global variable exposed by the package on the right.

Writing JavaScript OF THE FUTURE

JavaScript, like the rest of the web platform, is always being revised and improved. The next version of the JavaScript standard, called ES2015, includes many new language features that are not yet implemented in most browsers, but are interesting and useful additions. Take a look at this listing of new features in ES2015 for a better idea.

To get access to these features early, we can use Babel, which is a JavaScript compiler that brings features of future standards of JavaScript to browsers today. Fortunately for us, there is a transform for Browserify that runs code through Babel while doing the normal Browserify compilation. Getting Babel up and running is as simple as running:

npm install --save-dev babelify

And adding the transform to your Browserify task:

browserify: {
  options: {
    transform: ['browserify-shim', 'babelify']
  },
  dist: { files: { 'assets/js/main.js': 'assets/js/components/main.js' } }
}

Now whenever you compile your scripts using Browserify they are automatically run through Babel as well, so you are free to use the new features of ES2015 without fear of compatibility issues.

Welcome to the Next Ten Minutes

With those small changes to your Javascript workflow you have multi-file compiled ES2015 Javascript which plays nice with WordPress included scripts–pretty neat right?

Even cooler? If you use generator-plugin-wp, which I covered in a previous post, you get this workflow by default as of version 0.6.0! Just running yo plugin-wp:js in your plugin folder and selecting the Browserify option gives you properly shimmed jQuery (with everything setup to easily add other WordPress scripts you are using), and Babel running through Grunt!

Of course the Javascript ecosystem is evolving so quickly that there will be even bigger and better ways to do all of this and more! It always helps to keep your ears and eyes open for ways to keep improving and streamlining. Have any questions? Shoot ’em to me in the comments!