0
# Rollup Bublé Plugin
1

2
@rollup/plugin-buble is a Rollup plugin that integrates the Bublé compiler to transpile ES2015+ JavaScript code to ES5-compatible code. It provides a simple and lightweight alternative to Babel for basic ES2015+ transformations with fast compilation and minimal configuration overhead.
3

4
## Package Information
5

6
- **Package Name**: @rollup/plugin-buble
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rollup/plugin-buble --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import buble from '@rollup/plugin-buble';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const buble = require('@rollup/plugin-buble');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import buble from '@rollup/plugin-buble';
27

28
export default {
29
  input: 'src/index.js',
30
  output: {
31
    dir: 'output',
32
    format: 'cjs'
33
  },
34
  plugins: [buble()]
35
};
36
```
37

38
## Capabilities
39

40
### Plugin Creation
41

42
Creates a Rollup plugin instance that transforms ES2015+ code using the Bublé compiler.
43

44
```typescript { .api }
45
/**
46
 * Convert ES2015+ code with Bublé compiler
47
 * @param options - Configuration options for the plugin
48
 * @returns Rollup plugin instance
49
 */
50
function buble(options?: RollupBubleOptions): Plugin;
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
// Basic usage - no configuration needed
57
export default {
58
  plugins: [buble()]
59
};
60

61
// With transform options
62
export default {
63
  plugins: [buble({
64
    transforms: {
65
      forOf: false,
66
      dangerousForOf: true,
67
      arrow: true
68
    }
69
  })]
70
};
71

72
// With file filtering
73
export default {
74
  plugins: [buble({
75
    include: 'src/**/*.js',
76
    exclude: 'node_modules/**',
77
    transforms: { modules: false }
78
  })]
79
};
80
```
81

82
### File Filtering
83

84
Controls which files are processed by the plugin using picomatch patterns.
85

86
```typescript { .api }
87
interface RollupBubleOptions {
88
  /**
89
   * A picomatch pattern, or array of patterns, of files that should be
90
   * processed by this plugin (if omitted, all files are included by default)
91
   */
92
  include?: FilterPattern;
93
  /**
94
   * Files that should be excluded, if `include` is otherwise too permissive.
95
   */
96
  exclude?: FilterPattern;
97
}
98
```
99

100
**Examples:**
101

102
```javascript
103
// Include only specific files
104
buble({
105
  include: ['src/**/*.js', 'lib/**/*.js']
106
})
107

108
// Exclude node_modules
109
buble({
110
  exclude: 'node_modules/**'
111
})
112

113
// Complex patterns
114
buble({
115
  include: 'src/**/*.{js,jsx}',
116
  exclude: ['**/*.test.js', '**/fixtures/**']
117
})
118
```
119

120
### Transform Configuration
121

122
Configures Bublé compiler transformation options. All standard Bublé transform options are supported.
123

124
```typescript { .api }
125
interface RollupBubleOptions extends TransformOptions {
126
  /**
127
   * Bublé transformation options - controls which ES2015+ features to transform
128
   * The 'modules' option is automatically set to false for Rollup compatibility
129
   */
130
  transforms?: {
131
    [feature: string]: boolean;
132
  };
133
  
134
  /**
135
   * Additional Bublé compiler options
136
   */
137
  objectAssign?: boolean | string;
138
  target?: { [key: string]: any };
139
}
140
```
141

142
**Common Transform Options:**
143

144
```javascript
145
buble({
146
  transforms: {
147
    // Transform arrow functions (default: true)
148
    arrow: true,
149
    
150
    // Transform classes (default: true)
151
    classes: true,
152
    
153
    // Transform for-of loops (default: true)
154
    forOf: true,
155
    
156
    // Use dangerous for-of transform (faster but less safe)
157
    dangerousForOf: false,
158
    
159
    // Transform destructuring (default: true)
160
    destructuring: true,
161
    
162
    // Transform template literals (default: true)
163
    templateString: true,
164
    
165
    // Transform async/await (default: false - requires regenerator)
166
    asyncAwait: false,
167
    
168
    // Transform object spread (default: true)
169
    spreadRest: true
170
  },
171
  
172
  // Object.assign polyfill handling
173
  objectAssign: 'Object.assign', // or true for polyfill
174
  
175
  // Browser targets (affects which transforms are applied)
176
  target: {
177
    chrome: 58,
178
    firefox: 55,
179
    safari: 10,
180
    edge: 15
181
  }
182
})
183
```
184

185
## Types
186

187
```typescript { .api }
188
type FilterPattern = string | RegExp | Array<string | RegExp>;
189

190
interface TransformOptions {
191
  transforms?: { [key: string]: boolean };
192
  objectAssign?: boolean | string;
193
  target?: { [key: string]: any };
194
  source?: string;
195
  file?: string;
196
  includeContent?: boolean;
197
}
198

199
interface RollupBubleOptions extends TransformOptions {
200
  include?: FilterPattern;
201
  exclude?: FilterPattern;
202
}
203

204
interface Plugin {
205
  name: string;
206
  transform?: (code: string, id: string) => any;
207
}
208
```
209

210
## Error Handling
211

212
The plugin enhances Bublé compilation errors with additional context:
213

214
- **`e.plugin`**: Set to 'buble' to identify the source
215
- **`e.loc.file`**: The file path where the error occurred  
216
- **`e.frame`**: Code snippet showing the error location
217

218
**Error Example:**
219

220
```javascript
221
// If Bublé encounters invalid syntax:
222
// Error: Unexpected token (line 5, column 12)
223
// Plugin: buble
224
// File: /project/src/component.js
225
// Frame: [code snippet around error]
226
```
227

228
## Key Features
229

230
- **Fast Compilation**: Bublé is significantly faster than Babel for basic transformations
231
- **Zero Configuration**: Works out of the box with sensible defaults
232
- **Selective Transforms**: Choose exactly which ES2015+ features to transform
233
- **File Filtering**: Process only the files you need with include/exclude patterns
234
- **Rollup Integration**: Seamless integration with Rollup's plugin system
235
- **Error Enhancement**: Clear error messages with file context
236
- **Type Safety**: Full TypeScript support with complete type definitions