1[![NPM Status](https://img.shields.io/npm/v/babel-loader.svg?style=flat)](https://www.npmjs.com/package/babel-loader) 2[![Build Status](https://travis-ci.org/babel/babel-loader.svg?branch=master)](https://travis-ci.org/babel/babel-loader) 3[![Build Status](https://ci.appveyor.com/api/projects/status/vgtpr2i5bykgyuqo/branch/master?svg=true)](https://ci.appveyor.com/project/danez/babel-loader/branch/master) 4[![codecov](https://codecov.io/gh/babel/babel-loader/branch/master/graph/badge.svg)](https://codecov.io/gh/babel/babel-loader) 5 6<div align="center"> 7 <a href="https://github.com/babel/babel/"> 8 <img width="200" height="200" src="https://rawgit.com/babel/logo/master/babel.svg"> 9 </a> 10 <a href="https://github.com/webpack/webpack"> 11 <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg"> 12 </a> 13 <h1>Babel Loader</h1> 14</div> 15 16This package allows transpiling JavaScript files using [Babel](https://github.com/babel/babel) and [webpack](https://github.com/webpack/webpack). 17 18__Notes:__ Issues with the output should be reported on the babel [issue tracker](https://github.com/babel/babel/issues). 19 20<h2 align="center">Install</h2> 21 22> webpack 1.x | babel-loader <= 6.x 23> 24> webpack 2.x | babel-loader >= 7.x (recommended) (^6.2.10 will also work, but with deprecation warnings) 25> 26> webpack 3.x | babel-loader >= 7.1 27 28```bash 29yarn add babel-loader babel-core babel-preset-env webpack --dev 30``` 31 32We recommend using yarn, but you can also still use npm: 33 34```bash 35npm install --save-dev babel-loader babel-core babel-preset-env webpack 36``` 37 38<h2 align="center">Usage</h2> 39 40[Documentation: Using loaders](https://webpack.js.org/loaders/) 41 42Within your webpack configuration object, you'll need to add the babel-loader to the list of modules, like so: 43 44```javascript 45module: { 46 rules: [ 47 { 48 test: /\.js$/, 49 exclude: /(node_modules|bower_components)/, 50 use: { 51 loader: 'babel-loader', 52 options: { 53 presets: ['env'] 54 } 55 } 56 } 57 ] 58} 59``` 60 61### Options 62 63See the `babel` [options](https://babeljs.io/docs/usage/api/#options). 64 65 66You can pass options to the loader by using the [options property](https://webpack.js.org/configuration/module/#rule-options-rule-query): 67 68```javascript 69module: { 70 rules: [ 71 { 72 test: /\.js$/, 73 exclude: /(node_modules|bower_components)/, 74 use: { 75 loader: 'babel-loader', 76 options: { 77 presets: ['env'], 78 plugins: [require('babel-plugin-transform-object-rest-spread')] 79 } 80 } 81 } 82 ] 83} 84``` 85 86This loader also supports the following loader-specific option: 87 88* `cacheDirectory`: Default `false`. When set, the given directory will be used to cache the results of the loader. Future webpack builds will attempt to read from the cache to avoid needing to run the potentially expensive Babel recompilation process on each run. If the value is blank (`loader: 'babel-loader?cacheDirectory'`) or `true` (`loader: babel-loader?cacheDirectory=true`) the loader will use the default cache directory in `node_modules/.cache/babel-loader` or fallback to the default OS temporary file directory if no `node_modules` folder could be found in any root directory. 89 90* `cacheIdentifier`: Default is a string composed by the babel-core's version, the babel-loader's version, the contents of .babelrc file if it exists and the value of the environment variable `BABEL_ENV` with a fallback to the `NODE_ENV` environment variable. This can be set to a custom value to force cache busting if the identifier changes. 91 92* `forceEnv`: Default will resolve BABEL_ENV then NODE_ENV. Allow you to override BABEL_ENV/NODE_ENV at the loader level. Useful for isomorphic applications with different babel configuration for client and server. 93 94__Note:__ The `sourceMap` option is ignored, instead sourceMaps are automatically enabled when webpack is configured to use them (via the `devtool` config option). 95 96## Troubleshooting 97 98### babel-loader is slow! 99 100Make sure you are transforming as few files as possible. Because you are probably 101matching `/\.js$/`, you might be transforming the `node_modules` folder or other unwanted 102source. 103 104To exclude `node_modules`, see the `exclude` option in the `loaders` config as documented above. 105 106You can also speed up babel-loader by as much as 2x by using the `cacheDirectory` option. 107This will cache transformations to the filesystem. 108 109### babel is injecting helpers into each file and bloating my code! 110 111babel uses very small helpers for common functions such as `_extend`. By default 112this will be added to every file that requires it. 113 114You can instead require the babel runtime as a separate module to avoid the duplication. 115 116The following configuration disables automatic per-file runtime injection in babel, instead 117requiring `babel-plugin-transform-runtime` and making all helper references use it. 118 119See the [docs](http://babeljs.io/docs/plugins/transform-runtime/) for more information. 120 121**NOTE:** You must run `npm install babel-plugin-transform-runtime --save-dev` to include this in your project and `babel-runtime` itself as a dependency with `npm install babel-runtime --save`. 122 123```javascript 124rules: [ 125 // the 'transform-runtime' plugin tells babel to require the runtime 126 // instead of inlining it. 127 { 128 test: /\.js$/, 129 exclude: /(node_modules|bower_components)/, 130 use: { 131 loader: 'babel-loader', 132 options: { 133 presets: ['env'], 134 plugins: ['transform-runtime'] 135 } 136 } 137 } 138] 139``` 140 141#### **NOTE:** transform-runtime & custom polyfills (e.g. Promise library) 142 143Since [babel-plugin-transform-runtime](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-runtime) includes a polyfill that includes a custom [regenerator runtime](https://github.com/facebook/regenerator/blob/master/packages/regenerator-runtime/runtime.js) and [core.js](https://github.com/zloirock/core-js), the following usual shimming method using `webpack.ProvidePlugin` will not work: 144 145```javascript 146// ... 147 new webpack.ProvidePlugin({ 148 'Promise': 'bluebird' 149 }), 150// ... 151``` 152 153The following approach will not work either: 154 155```javascript 156require('babel-runtime/core-js/promise').default = require('bluebird'); 157 158var promise = new Promise; 159``` 160 161which outputs to (using `runtime`): 162 163```javascript 164'use strict'; 165 166var _Promise = require('babel-runtime/core-js/promise')['default']; 167 168require('babel-runtime/core-js/promise')['default'] = require('bluebird'); 169 170var promise = new _Promise(); 171``` 172 173The previous `Promise` library is referenced and used before it is overridden. 174 175One approach is to have a "bootstrap" step in your application that would first override the default globals before your application: 176 177```javascript 178// bootstrap.js 179 180require('babel-runtime/core-js/promise').default = require('bluebird'); 181 182// ... 183 184require('./app'); 185``` 186 187### The node API for `babel` has been moved to `babel-core`. 188 189If you receive this message it means that you have the npm package `babel` installed and use the short notation of the loader in the webpack config (which is not valid anymore as of webpack 2.x): 190```js 191 { 192 test: /\.js$/, 193 loader: 'babel', 194 } 195``` 196 197Webpack then tries to load the `babel` package instead of the `babel-loader`. 198 199To fix this you should uninstall the npm package `babel` as it is deprecated in babel v6. (instead install `babel-cli` or `babel-core`) 200In the case one of your dependencies is installing `babel` and you cannot uninstall it yourself, use the complete name of the loader in the webpack config: 201```js 202 { 203 test: /\.js$/, 204 loader: 'babel-loader', 205 } 206``` 207 208## [License](http://couto.mit-license.org/) 209