1 | # babel-preset-airbnb
|
2 |
|
3 | > A babel preset for transforming your JavaScript for Airbnb.
|
4 |
|
5 | Currently contains transforms for all [stage 4](https://tc39.github.io/ecma262/) (ES2018) and [stage 3](https://github.com/tc39/proposals#active-proposals) syntax that is permitted in the [Airbnb Style Guide](https://github.com/airbnb/javascript). Please note that if usage of a stage 3 proposal is not explicitly mentioned in the Airbnb Style Guide, then it will not be enabled here. Additionally, stage 4 syntax that is excluded is as follows:
|
6 | - generators: `regenerator-runtime` is too heavyweight for our use.
|
7 | - `async/await`: `regenerator-runtime` is too heavyweight for our use, and [async-to-promises](https://www.npmjs.com/package/babel-plugin-async-to-promises) is not yet complete enough to be safely used.
|
8 | - async iterators: depends on both generators and `async function`s
|
9 | - lifted template literal restrictions: we do not use tagged template literals, nor implement custom DSLs, otherwise we would enable this.
|
10 |
|
11 | ## Install
|
12 |
|
13 | ```sh
|
14 | $ npm install --save-dev babel-preset-airbnb
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ### Via `.babelrc` (Recommended)
|
20 |
|
21 | **.babelrc**
|
22 |
|
23 | ```json
|
24 | {
|
25 | "presets": ["airbnb"]
|
26 | }
|
27 | ```
|
28 |
|
29 | ### Via CLI
|
30 |
|
31 | ```sh
|
32 | $ babel script.js --presets airbnb
|
33 | ```
|
34 |
|
35 | ### Via Node API
|
36 |
|
37 | ```javascript
|
38 | require('@babel/core').transform('code', {
|
39 | presets: ['airbnb']
|
40 | });
|
41 | ```
|
42 |
|
43 | ### Targeting Environments
|
44 |
|
45 | This module uses @babel/preset-env to target specific environments.
|
46 |
|
47 | Please refer to [@babel/preset-env#targets](https://babeljs.io/docs/en/babel-preset-env#targets) for a list of available options.
|
48 |
|
49 | For a list of browsers please see [browserlist](https://github.com/ai/browserslist).
|
50 |
|
51 | You may override our default list of targets by providing your own `targets` key.
|
52 |
|
53 | ```json
|
54 | {
|
55 | "presets": [["airbnb", {
|
56 | "targets": {
|
57 | "chrome": 50,
|
58 | "ie": 11,
|
59 | "firefox": 45
|
60 | }
|
61 | }]]
|
62 | }
|
63 | ```
|
64 |
|
65 | The following transpiles only for Node v6.
|
66 |
|
67 | ```json
|
68 | {
|
69 | "presets": [["airbnb", {
|
70 | "targets": {
|
71 | "node": 6
|
72 | }
|
73 | }]]
|
74 | }
|
75 | ```
|
76 |
|
77 | If you wish, you can also inherit our default list of browsers and extend them using `additionalTargets`.
|
78 |
|
79 | ```json
|
80 | {
|
81 | "presets": [["airbnb", {
|
82 | "additionalTargets": {
|
83 | "chrome": 42,
|
84 | "ie": 8
|
85 | }
|
86 | }]]
|
87 | }
|
88 | ```
|
89 |
|
90 | You may override our default debug option by providing your own `debug` key.
|
91 |
|
92 | ```json
|
93 | {
|
94 | "presets": [["airbnb", {
|
95 | "debug": true
|
96 | }]]
|
97 | }
|
98 | ```
|
99 |
|
100 | ## React Development Mode
|
101 |
|
102 | When `process.env.NODE_ENV` is `'development'`, [the `development` mode will be set for `@babel/preset-react`](https://babeljs.io/docs/en/babel-preset-react#development).
|
103 |
|
104 | You may override our default development option by providing your own boolean `development` key.
|
105 |
|
106 | ```json
|
107 | {
|
108 | "presets": [["airbnb", {
|
109 | "development": false
|
110 | }]]
|
111 | }
|
112 | ```
|
113 |
|
114 | ## React PropTypes removal
|
115 |
|
116 | This preset can be configured to remove propTypes using [babel-plugin-transform-react-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types) with the following default options:
|
117 |
|
118 |
|
119 | To enable this transformation with the default options, set the `removePropTypes` option to `true`:
|
120 |
|
121 | ```json
|
122 | {
|
123 | "presets": [["airbnb", {
|
124 | "removePropTypes": true
|
125 | }]]
|
126 | }
|
127 | ```
|
128 |
|
129 | The default options that will be used are:
|
130 |
|
131 | ```js
|
132 | {
|
133 | mode: 'wrap',
|
134 | additionalLibraries: ['airbnb-prop-types'],
|
135 | ignoreFilenames: ['node_modules'],
|
136 | }
|
137 | ```
|
138 |
|
139 | Default options can be overridden using the `removePropTypes` option. These options will be shallow-merged with the defaults:
|
140 |
|
141 | ```json
|
142 | {
|
143 | "presets": [["airbnb", {
|
144 | "removePropTypes": {
|
145 | "mode": "remove"
|
146 | }
|
147 | }]]
|
148 | }
|
149 | ```
|
150 |
|
151 | For example, if you are using this plugin in a deployable app, you might want to use the remove mode for your production build (and disable this transform entirely in development for optimal build speeds).
|
152 |
|
153 | ## Classes loose mode
|
154 |
|
155 | By default, this preset will compile classes in normal mode. This is safer, but comes with a bundle size and runtime overhead. To [compile classes in loose mode](https://babeljs.io/docs/en/babel-plugin-transform-classes#loose), set the `looseClasses` option to `true`:
|
156 |
|
157 | ```json
|
158 | {
|
159 | "presets": [["airbnb", {
|
160 | "looseClasses": true,
|
161 | }]]
|
162 | }
|
163 | ```
|
164 |
|
165 | The [risks of enabling loose classes are outlined in the Babel docs](https://babeljs.io/docs/en/babel-plugin-transform-classes#loose).
|
166 |
|
167 | ## Specifying a babel runtime version
|
168 |
|
169 | By default @babel/plugin-transform-runtime will [assume the oldest version of the runtime](https://github.com/babel/babel/blob/e6264a09921c60b8f18870d0a75678e4fa04f0f8/packages/babel-plugin-transform-runtime/src/index.js#L42) to avoid importing helpers that don't exist which would fail at runtime. This can result in newer helpers being inlined into modules (ex. objectSpread2) which increases bundle size.
|
170 |
|
171 | To avoid this you can configure the preset to use the same version of the runtime that's installed in your package.json.
|
172 |
|
173 | ex. If package.json has `"@babel/runtime": "^7.5.5"` then you can use:
|
174 |
|
175 | ```json
|
176 | {
|
177 | "presets": [["airbnb", {
|
178 | "runtimeVersion": "7.5.5",
|
179 | }]]
|
180 | }
|
181 | ```
|
182 |
|
183 | Note that this will result in a runtime breakage if the version passed into the airbnb preset is newer than the version of the babel runtime actually being used at build time.
|
184 |
|
185 | ## Disabling `plugin-transform-runtime`
|
186 |
|
187 | You can use the `transformRuntime` option to disable [`@babel/plugin-transform-runtime`](https://babeljs.io/docs/en/babel-plugin-transform-runtime). Specifying `false` will disable the plugin. This option defaults to `true`.
|
188 |
|
189 | ## Specifying module transforms
|
190 |
|
191 | You can use the `modules` option to enable transformation of modules given to this preset:
|
192 |
|
193 | ```json
|
194 | {
|
195 | "presets": [["airbnb", {
|
196 | "modules": "auto"
|
197 | }]]
|
198 | }
|
199 | ```
|
200 |
|
201 | Both `true` and the option default `auto` will not transform modules if ES6 module syntax is already supported by the environment, or `"commonjs"` otherwise. `false` will not transform modules.
|
202 |
|
203 | You can use the `runtimeHelpersUseESModules` option to prevent transformation of runtime helpers to CommonJS modules.
|
204 |
|
205 | ```json
|
206 | {
|
207 | "presets": [["airbnb", {
|
208 | "runtimeHelpersUseESModules": true
|
209 | }]]
|
210 | }
|
211 | ```
|
212 |
|
213 | `true` will not transform runtime helpers to CommonJS modules. `false` will transform runtime helpers to CommonJS modules. The option defaults to `true` if `modules` is set to `false`, and `false` otherwise.
|