0
# @vue/babel-preset-app
1

2
@vue/babel-preset-app is the default Babel preset used exclusively in Vue CLI projects. It provides comprehensive JavaScript/TypeScript transpilation and polyfill management with smart defaults for browser compatibility, automatic feature detection, and environment-specific optimizations.
3

4
## Package Information
5

6
- **Package Name**: @vue/babel-preset-app
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @vue/babel-preset-app` (typically installed as part of Vue CLI)
10

11
## Core Imports
12

13
```javascript
14
// CommonJS
15
const preset = require('@vue/babel-preset-app');
16

17
// ES modules (if supported)
18
import preset from '@vue/babel-preset-app';
19
```
20

21
## Basic Usage
22

23
```javascript
24
// babel.config.js
25
module.exports = {
26
  presets: [
27
    '@vue/babel-preset-app'
28
  ]
29
};
30

31
// With options
32
module.exports = {
33
  presets: [
34
    ['@vue/babel-preset-app', {
35
      targets: { node: 'current' },
36
      useBuiltIns: 'usage',
37
      polyfills: ['es.promise', 'es.object.assign']
38
    }]
39
  ]
40
};
41
```
42

43
## Architecture
44

45
@vue/babel-preset-app is built around several key components:
46

47
- **@babel/preset-env Integration**: Automatically determines transforms and polyfills based on browser targets
48
- **Vue JSX Support**: Conditional JSX support for Vue 2 (@vue/babel-preset-jsx) and Vue 3 (@vue/babel-plugin-jsx)
49
- **Polyfill Management**: Custom polyfill injection plugin for precise core-js polyfill control
50
- **Environment Detection**: Automatic configuration for different build contexts (webpack, Jest, modern build)
51
- **Runtime Optimization**: Transform-runtime integration for helper deduplication
52

53
## Capabilities
54

55
### Preset Function
56

57
The main preset export that returns Babel configuration based on context and options.
58

59
```javascript { .api }
60
/**
61
 * Main preset function that returns Babel configuration
62
 * @param {Object} context - Babel context object (automatically provided by Babel)
63
 * @param {PresetOptions} options - Configuration options
64
 * @returns {BabelConfig} Babel configuration object with presets, plugins, and overrides
65
 */
66
function preset(context, options = {});
67

68
interface PresetOptions {
69
  // @babel/preset-env options
70
  targets?: string | string[] | { [key: string]: string };
71
  modules?: 'amd' | 'umd' | 'systemjs' | 'commonjs' | 'cjs' | 'auto' | false;
72
  useBuiltIns?: 'usage' | 'entry' | false;
73
  loose?: boolean;
74
  debug?: boolean;
75
  spec?: boolean;
76
  ignoreBrowserslistConfig?: boolean;
77
  configPath?: string;
78
  include?: string[];
79
  exclude?: string[];
80
  forceAllTransforms?: boolean;
81
  shippedProposals?: boolean;
82
  bugfixes?: boolean;
83
  
84
  // Vue CLI specific options
85
  polyfills?: string[];
86
  jsx?: boolean | object;
87
  entryFiles?: string[];
88
  absoluteRuntime?: string | boolean;
89
  version?: string;
90
  decoratorsBeforeExport?: boolean;
91
  decoratorsLegacy?: boolean;
92
}
93

94
interface BabelConfig {
95
  sourceType: 'unambiguous';
96
  overrides: Array<{
97
    exclude?: RegExp[];
98
    include?: RegExp[];
99
    presets: Array<[any, object] | any>;
100
    plugins: Array<[any, object] | any>;
101
  }>;
102
}
103
```
104

105
### Core Configuration Options
106

107
#### targets
108
- **Type**: `string | string[] | object`
109
- **Default**: Browserslist config or auto-detected based on environment
110
- **Description**: Browser/environment targets for transpilation
111

112
```javascript
113
// Examples
114
targets: { ie: 9, chrome: 58 }
115
targets: '> 1%, last 2 versions'
116
targets: { node: 'current' } // Automatically set in test environment
117
```
118

119
#### useBuiltIns
120
- **Type**: `'usage' | 'entry' | false`
121
- **Default**: `'usage'`
122
- **Description**: Strategy for including polyfills
123

124
```javascript
125
// Usage-based polyfill injection (default)
126
useBuiltIns: 'usage'
127

128
// Manual polyfill entry
129
useBuiltIns: 'entry'
130

131
// No automatic polyfills
132
useBuiltIns: false
133
```
134

135
#### modules
136
- **Type**: `'amd' | 'umd' | 'systemjs' | 'commonjs' | 'cjs' | 'auto' | false`
137
- **Default**: `false` (preserve ES modules), `'commonjs'` in Jest tests
138
- **Description**: Module format for output
139

140
### Vue-Specific Options
141

142
#### polyfills
143
- **Type**: `string[]`
144
- **Default**: `['es.array.iterator', 'es.promise', 'es.object.assign', 'es.promise.finally']`
145
- **Description**: Core-js polyfills to pre-include when using `useBuiltIns: 'usage'`
146

147
```javascript
148
polyfills: [
149
  'es.promise',
150
  'es.object.assign',
151
  'es.array.includes'
152
]
153
```
154

155
#### jsx
156
- **Type**: `boolean | object`
157
- **Default**: `true`
158
- **Description**: Enable Vue JSX support and pass options to JSX plugins
159

160
```javascript
161
// Enable JSX (default)
162
jsx: true
163

164
// Disable JSX
165
jsx: false
166

167
// JSX with options (Vue 2)
168
jsx: {
169
  injectH: false,
170
  vModel: false
171
}
172

173
// JSX with options (Vue 3)
174
jsx: {
175
  transformOn: true,
176
  optimize: false
177
}
178
```
179

180
#### entryFiles
181
- **Type**: `string[]`
182
- **Default**: `[]` (from `VUE_CLI_ENTRY_FILES` environment variable)
183
- **Description**: List of entry files for polyfill injection in multi-page applications
184

185
```javascript
186
entryFiles: [
187
  './src/main.js',
188
  './src/admin.js'
189
]
190
```
191

192
#### absoluteRuntime
193
- **Type**: `string | boolean`
194
- **Default**: Path to @babel/runtime package
195
- **Description**: Use absolute paths for runtime helpers to ensure version consistency
196

197
```javascript
198
// Use absolute path (default)
199
absoluteRuntime: '/path/to/node_modules/@babel/runtime'
200

201
// Use relative paths
202
absoluteRuntime: false
203
```
204

205
### Advanced Options
206

207
#### loose
208
- **Type**: `boolean`
209
- **Default**: `false`
210
- **Description**: Enable loose mode transforms for better performance but less spec compliance
211

212
#### decoratorsLegacy
213
- **Type**: `boolean`
214
- **Default**: `true`
215
- **Description**: Use legacy decorator semantics
216

217
#### version
218
- **Type**: `string`
219
- **Default**: Version of installed @babel/runtime
220
- **Description**: Runtime version for transform-runtime plugin
221

222
### Environment Variables
223

224
The preset responds to several environment variables for automatic configuration:
225

226
```javascript { .api }
227
interface EnvironmentVariables {
228
  VUE_CLI_BABEL_TARGET_NODE?: 'true'; // Set targets to { node: 'current' }
229
  VUE_CLI_BABEL_TRANSPILE_MODULES?: 'true'; // Set modules to 'commonjs'
230
  VUE_CLI_BUILD_TARGET?: 'app' | 'wc' | 'wc-async'; // Adjust targets for build type
231
  VUE_CLI_MODERN_BUILD?: 'true'; // Use modern browser targets
232
  VUE_CLI_ENTRY_FILES?: string; // JSON array of entry files
233
  VUE_CLI_TEST?: 'true'; // Test mode flag
234
  VUE_CLI_TRANSPILE_BABEL_RUNTIME?: 'true'; // Internal flag for @vue/cli-plugin-babel to transpile @babel/runtime
235
  NODE_ENV?: 'test' | 'development' | 'production'; // Automatic test mode detection
236
}
237
```
238

239
### Return Value Structure
240

241
The preset returns a Babel configuration with specific overrides:
242

243
```javascript { .api }
244
interface BabelConfigOutput {
245
  sourceType: 'unambiguous';
246
  overrides: [
247
    {
248
      // Main application code
249
      exclude: [/@babel[/|\\\\]runtime/, /core-js/];
250
      presets: Array<[any, object]>; // @babel/preset-env + Vue JSX presets
251
      plugins: Array<[any, object]>; // Transform plugins + polyfill injection
252
    },
253
    {
254
      // @babel/runtime transpilation
255
      include: [/@babel[/|\\\\]runtime/];
256
      presets: Array<[any, object]>; // @babel/preset-env only
257
    }
258
  ];
259
}
260
```
261

262
### Usage Examples
263

264
**Basic Vue CLI Project:**
265
```javascript
266
// babel.config.js (automatically generated by Vue CLI)
267
module.exports = {
268
  presets: [
269
    '@vue/babel-preset-app'
270
  ]
271
};
272
```
273

274
**Custom Browser Targets:**
275
```javascript
276
module.exports = {
277
  presets: [
278
    ['@vue/babel-preset-app', {
279
      targets: {
280
        browsers: ['> 1%', 'last 2 versions', 'not ie <= 8']
281
      }
282
    }]
283
  ]
284
};
285
```
286

287
**Library Mode (No Polyfills):**
288
```javascript
289
module.exports = {
290
  presets: [
291
    ['@vue/babel-preset-app', {
292
      useBuiltIns: false,
293
      jsx: false
294
    }]
295
  ]
296
};
297
```
298

299
**Node.js/Testing Configuration:**
300
```javascript
301
module.exports = {
302
  presets: [
303
    ['@vue/babel-preset-app', {
304
      targets: { node: 'current' },
305
      modules: 'commonjs'
306
    }]
307
  ]
308
};
309
```
310

311
**Multi-page Application:**
312
```javascript
313
module.exports = {
314
  presets: [
315
    ['@vue/babel-preset-app', {
316
      entryFiles: [
317
        './src/main.js',
318
        './src/admin.js',
319
        './src/mobile.js'
320
      ]
321
    }]
322
  ]
323
};
324
```
325

326
### Error Handling
327

328
The preset includes validation for polyfill names:
329

330
```javascript
331
// Will throw error if polyfill doesn't exist in core-js-compat
332
polyfills: ['invalid.polyfill'] // Error: Cannot find polyfill invalid.polyfill
333
```
334

335
Common error patterns:
336
- Invalid polyfill names are validated against core-js-compat
337
- Missing peer dependencies (Vue, @babel/core, core-js) will cause runtime errors
338
- Conflicting options between preset-env and custom settings are resolved with preset defaults
339

340
## Types
341

342
```javascript { .api }
343
interface DefaultPolyfills {
344
  'es.array.iterator': string;
345
  'es.promise': string;
346
  'es.object.assign': string;
347
  'es.promise.finally': string;
348
}
349

350
interface PolyfillPlugin {
351
  name: 'vue-cli-inject-polyfills';
352
  visitor: {
353
    Program(path: any, state: { filename: string }): void;
354
  };
355
}
356

357
interface TargetEnvironments {
358
  browsers?: string | string[];
359
  node?: string | 'current';
360
  esmodules?: boolean;
361
  chrome?: string;
362
  firefox?: string;
363
  safari?: string;
364
  edge?: string;
365
  ie?: string;
366
  ios?: string;
367
  android?: string;
368
  electron?: string;
369
}
370
```