ES6 And Beyond / Adding Babel To Your Project

Bettina Pschorr
Nov 8 · 6 min read

This article outlines how to add Babel to an existing project using Gulp as a build toolkit. It also includes tips for Karma, Bower and RequireJS users. :)

Before we start — Karma is not necessary to install Babel. If you’re not interested in/you’re not already using Karma, you can ignore the Karma sections. I’ve just included them here for those who use Karma as a testing framework.

Why Babel?

Babel is a tool primarily used to convert ES6+ code into a backwards compatible version of JavaScript which current and older browsers can understand. JavaScript is constantly changing. As JavaScript engineers, it’s important we keep ourselves up-to-date and familiarize ourselves with the evolving syntax. Browsers, however, take a longer time to understand the changing syntax, and there is no guarantee some of them will ever catch up.

Enter Babel.

Babel enables us to write whatever ES-version syntax we like in our code without the consideration of which browsers can support it. We don’t have to refrain from writing fat arrow functions because we know IE doesn’t understand them. Babel will compile it into something all browsers can understand.

Installing Packages

Here are the packages we’re going to be using:

@babel/core

@babel/cli to use Babel from the command line

@babel/preset-env is a set of predetermined plugins bundled together so we don’t have to pick and choose which plugins to install individually

gulp-babel to use Babel with Gulp

karma-babel-preprocessor to use Babel with Karma as a preprocessor

Install these dependencies as devDependencies by running the following command:

npm i — save-dev @babel/core @babel/cli @babel/preset-env gulp-babel karma-babel-preprocessor

Configuring Babel

gulpfile.js

This is where we import the gulp-babel package and create a Gulp task to apply Babel to our code. Here’s what the code looks like:

We imported Babel. Then, we added a Gulp task to apply Babel to our project directory. Then, we added it to our build task.

Note: We’re only applying Babel to our JS files. Hence, the *.js paths.

Ensure you are setting the destination correctly, so all the tasks which follow pick up the new Babelified files.

.babelrc

In order to enable our preset, we must define it somewhere. I’ve chosen to define it in a .babelrc file:

Alternatively, we could’ve added this to our package.json file or a babel.config.js file. Find instructions for that here.

karma.conf.js

This is where we add our karma-babel preprocessor, specifying which plugins/presets to use. We’ll use our preset-env and add it to our preprocessors for both our test files and our source code. This enables us to write ES6 in the tests themselves, as well as have our tests understand ES6 syntax in our source code (the files they are testing).

If the paths are a little confusing or if you’re asking how the path “src/**/*.js” includes both test files and source code, here’s what my project folder structure looks like:

src/

. . js/

. . . . source code

. . test/

. . . . test files

Of course, if you want to apply the Babel preprocessor to only certain files, you can specify a more targeted path.

Polyfills

The preset-env compiles most ES6 syntax into ES5, but what about ES7 features like async/await? JavaScript is constantly evolving; I mean we’re already onto ES9! That’s where polyfills come into play.

  1. If your project uses NPM or Yarn as its package manager, you can simply “npm install — save babel-polyfill” and treat it as you do your other dependencies. You can skip the next step.
  2. If your project still uses Bower (as mine unfortunately does), you’ll have to download and add the static polyfill file yourself. To do this, run “npm install babel-polyfill”. Locate the polyfill.min.js file. Move it to your project’s shared directory (or a folder of your choice). Check this file into Git.
  3. Note: babel-polyfill needs to be a regular dependency, not a devDependency. This is because polyfills need to run before your source code to work.
  4. Import the polyfill file at the top of your project. For me, this was init.js. Yours might be named main.js.
  5. If you’re using RequireJS, you’ll also need to require it at the top of your project (the same file you imported it in).
Step 4: Import the polyfill file at the top of your project.
Step 4 if you’re using RequireJS.
Step 5 if you’re using RequireJS.

For Karma, you’ll need to add it as the first of your files to load in the browser:

karma.conf.js

Your paths will likely be different and that’s fine. Just make sure it’s the first file you load. If you’re curious, this is because the polyfill file contains functions used by Babel to transpile the code in later files.

Testing Babel

Great! We’ve installed and configured Babel. How do we know Babel is working in our project?

  1. Check the Babelified files. Execute the Babel Gulp task on its own (not the build task) and check the destination directory. The files should have been transpiled by Babel and moved to the location we specified. We can test this by writing an arrow function or some other ES6 syntax in one of our original files. Then, find the same file in the destination folder and verify the arrow function has been transpiled into ES5 syntax.
  2. Test the build in your browser. Running our source code directly in the browser won’t show us if Babel did its job because it is using our original files. Run the server in your dist folder (or whatever directory you’re sending your build files to). Once you’ve used some ES6+ syntax in your code and built your project with the Babel task in your pipeline, open your build .html file in your browser and check the console. It should not cause any errors. Make sure to test in a browser like Internet Explorer, which we know doesn’t understand ES6+ syntax. Chrome will likely still work because it’s adopted many of the features already. A good way to test is making sure it causes errors (see the next section on what kind of errors) in the browser before you apply Babel and, after Babel, those errors should go away.

Common Errors

  • “Use-strict” errors

Babel operates in strict mode. If your project isn’t following the strict mode conventions, you’ll likely get some errors. These are relatively easy to fix — they’re mostly to do with undeclared variables (forgetting a var) and objects that shouldn’t be tampered with (i.e. the window object).

  • “Unexpected token…”

This is a syntax error. Babel probably wasn’t applied to your code properly. Make sure you do the two checks from the previous section.

  • “Can’t find variable: regeneratorRuntime”

It’s trying (and failing) to find functions from the polyfill I mentioned earlier. Make sure you’ve imported/required it properly and the path is correct.

Congratulations!

We’ve successfully added Babel to our project! We learned how to install and configure Babel, how to add polyfills, how to test everything and we’ve even looked at some common errors to watch out for. Give it a clap if you found this useful or drop a comment if you didn’t (or just to say hi). Happy coding!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade