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.
Install
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.
- Different projects on the same machine can depend on different versions of Babel allowing you to update them individually.
- 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
Copy
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"
}
}
Usage
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.
Installation
npm install --save @babel/polyfill
copy
Because this is a polyfill (which will run before your source code), we need it to be a dependency, not a devDependency
Size
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!
require("@babel/polyfill");
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.
Details
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.