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