Babel CLI & Babel Polyfill Tutorial

Babel CLI

Babel comes with a built-in CLI which can be used to compile files from the command line.

In addition, various entry point scripts live in the top-level package at @babel/cli/bin. There is a shell-executable utility script, babel-external-helpers.js, and the main Babel cli script, babel.js.


While you can install Babel CLI globally on your machine, it’s much better to install it locally project by project.

There are two primary reasons for this.

  1. Different projects on the same machine can depend on different versions of Babel allowing you to update them individually.
  2. Not having an implicit dependency on the environment you are working in makes your project far more portable and easier to setup.

We can install Babel CLI locally by running:

npm install --save-dev @babel/core @babel/cli

Note: If you do not have a package.json, create one before installing. This will ensure proper interaction with the npx command.

After that finishes installing, your package.json file should include:

 "devDependencies": {
+   "@babel/cli": "^7.0.0",
+   "@babel/core": "^7.0.0"


babel script.js

Note: These instructions use the excellent npx command to run the locally installed executables. You can drop it inside of an npm run script or you may instead execute with the relative path instead. ./node_modules/.bin/babel

Compile Files

Compile the file script.js and output to stdout.

npx babel script.js
# output...

If you would like to output to a file you may use –out-file or -o.

npx babel script.js --out-file script-compiled.js

To compile a file every time that you change it, use the –watch or -w option:npx babel script.js –watch –out-file script-compiled.js

Compile with Source Maps

If you would then like to add a source map file you can use –source-maps or -s. Learn more about source maps.

npx babel script.js --out-file script-compiled.js --source-maps

Or, if you’d rather have inline source maps, use –source-maps inline instead.npx babel script.js –out-file script-compiled.js –source-maps inline

Compile Directories

Compile the entire src directory and output it to the lib directory by using either –out-dir or -d. This doesn’t overwrite any other files or directories in lib.

npx babel src --out-dir lib

Compile the entire src directory and output it as a single concatenated file.npx babel src –out-file script-compiled.js

Ignore files

Ignore spec and test files

npx babel src --out-dir lib --ignore "src/**/*.spec.js","src/**/*.test.js"

Copy files

Copy files that will not be compilednpx babel src –out-dir lib –copy-files

npx babel src --out-dir lib --copy-files

Piping Files

Pipe a file in via stdin and output it to script-compiled.js

npx babel --out-file script-compiled.js < script.js

Using Plugins

Use the –plugins option to specify plugins to use in compilation

npx babel script.js --out-file script-compiled.js --plugins=@babel/proposal-class-properties,@babel/transform-modules-amd

Using Presets

Use the –presets option to specify plugins to use in compilation

npx babel script.js --out-file script-compiled.js --presets=@babel/preset-env,@babel/flow

Ignoring .babelrc

Ignore the configuration from the project’s .babelrc file and use the cli options e.g. for a custom build

 npx babel --no-babelrc script.js --out-file script-compiled.js --presets=es2015,react

Advanced Usage

There are many more options available, babel –help and other sections for more information.

Babel Polyfill

Babel includes a polyfill that includes a custom regenerator runtime and core-js.

This will emulate a full ES2015+ environment (no < Stage 4 proposals) and is intended to be used in an application rather than a library/tool. (this polyfill is automatically loaded when using babel-node).

This means you can use new built-ins like Promise or WeakMap, static methods like Array.from or Object.assign, instance methods like Array.prototype.includes, and generator functions (provided you use the regenerator plugin). The polyfill adds to the global scope as well as native prototypes like String in order to do this.


npm install --save @babel/polyfill

Because this is a polyfill (which will run before your source code), we need it to be a dependency, not a devDependency


The polyfill is provided as a convenience but you should use it with @babel/preset-env and the useBuiltIns option so that it doesn’t include the whole polyfill which isn’t always needed. Otherwise, we would recommend you import the individual polyfills manually.

TC39 Proposals

If you need to use a proposal that is not Stage 4, @babel/polyfill will not automatically import those for you. You will have to import those from another polyfill like core-js individually. We may work towards including this as separate files in @babel/polyfill soon.

Usage in Node / Browserify / Webpack

To include the polyfill you need to require it at the top of the entry point to your application.

Make sure it is called before all other code/require statements!


If you are using ES6’s import syntax in your application’s entry point, you should instead import the polyfill at the top of the entry point to ensure the polyfills are loaded first:

import "@babel/polyfill";

With webpack, there are multiple ways to include the polyfills:

  • When used alongside @babel/preset-env,
    • If useBuiltIns: ‘usage’ is specified in .babelrc then do not include @babel/polyfill in either webpack.config.js entry array nor source. Note, @babel/polyfill still needs to be installed.
    • If useBuiltIns: ‘entry’ is specified in .babelrc then include @babel/polyfill at the top of the entry point to your application via require or import as discussed above.
    • If useBuiltIns key is not specified or it is explicitly set with useBuiltIns: false in your .babelrc, add @babel/polyfill directly to the entry array in your webpack.config.js.
module.exports = {
 entry: ["@babel/polyfill", "./app/js"],
  • If @babel/preset-env is not used then add @babel/polyfill to webpack entry array as discussed above. It can still be added at the top of the entry point to application via import or require, but this is not recommended.

We do not recommend that you import the whole polyfill directly: either try the useBuiltInsoptions or import only the polyfills you need manually (either from this package or somewhere else).

Usage in Browser

Available from the dist/polyfill.js file within a @babel/polyfill npm release. This needs to be included before all your compiled Babel code. You can either prepend it to your compiled code or include it in a <script> before it.

NOTE: Do not require this via browserify etc, use @babel/polyfill.


If you are looking for something that won’t modify globals to be used in a tool/library, checkout the transform-runtime plugin. This means you won’t be able to use the instance methods mentioned above like Array.prototype.includes.

Note: Depending on what ES2015 methods you actually use, you may not need to use @babel/polyfill or the runtime plugin. You may want to only load the specific polyfills you are using(like Object.assign) or just document that the environment the library is being loaded in should include certain polyfills.

Related JavaScript Tutorials For Beginners

JavaScript Introduction Tutorials
Introduction to JavaScript
Javascript Code editors
Javascript Reference and Specifications
Javascript Developer Console
Javascript Basics
JavaScript Hello World.!
External JavaScript Files
JavaScript Code Structure
JavaScript Variables
Use Strict in JavaScript

Leave a Comment