0
# Main Plugin
1

2
The main esbuild plugin function provides comprehensive TypeScript/JavaScript transformation, compilation, and optional minification within the Rollup build pipeline.
3

4
## Capabilities
5

6
### Main Plugin Function
7

8
Creates a Rollup plugin that transforms TypeScript/JavaScript files using esbuild's fast compilation engine.
9

10
```typescript { .api }
11
/**
12
 * Creates a Rollup plugin for esbuild transformation
13
 * @param options - Configuration options for the plugin
14
 * @returns Rollup plugin instance
15
 */
16
function esbuild(options?: Options): RollupPlugin;
17

18
interface Options {
19
  // File filtering
20
  include?: FilterPattern;
21
  exclude?: FilterPattern;
22
  
23
  // Source maps
24
  sourceMap?: boolean;
25
  
26
  // Dependency optimization
27
  optimizeDeps?: OptimizeDepsOptions;
28
  
29
  // TypeScript configuration
30
  tsconfig?: string | false;
31
  
32
  // Custom loaders
33
  loaders?: { [ext: string]: Loader | false };
34
  
35
  // Minification options
36
  minify?: boolean;
37
  minifyWhitespace?: boolean;
38
  minifyIdentifiers?: boolean;
39
  minifySyntax?: boolean;
40
  
41
  // Compilation target
42
  target?: string | string[];
43
  
44
  // JSX transformation
45
  jsx?: "transform" | "preserve" | "automatic";
46
  jsxFactory?: string;
47
  jsxFragment?: string;
48
  jsxImportSource?: string;
49
  jsxDev?: boolean;
50
  
51
  // Code transformation
52
  define?: { [key: string]: string };
53
  charset?: "ascii" | "utf8";
54
  treeShaking?: boolean;
55
  ignoreAnnotations?: boolean;
56
  legalComments?: "none" | "inline" | "eof" | "linked" | "external";
57
  keepNames?: boolean;
58
  format?: "iife" | "cjs" | "esm";
59
  globalName?: string;
60
  
61
  // Advanced minification
62
  mangleProps?: RegExp;
63
  reserveProps?: RegExp;
64
  mangleQuoted?: boolean;
65
  mangleCache?: { [key: string]: string | false };
66
  drop?: ("console" | "debugger")[];
67
  dropLabels?: string[];
68
}
69

70
type FilterPattern = string | RegExp | (string | RegExp)[];
71
type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "text" | "base64" | "binary" | "dataurl";
72

73
interface OptimizeDepsOptions {
74
  include: string[];
75
  exclude?: string[];
76
  cwd: string;
77
  esbuildOptions?: any;
78
  sourceMap: boolean;
79
}
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import esbuild from "rollup-plugin-esbuild";
86

87
// Basic TypeScript compilation
88
export default {
89
  plugins: [
90
    esbuild({
91
      include: /\.[jt]sx?$/,
92
      exclude: /node_modules/,
93
      target: "es2020"
94
    })
95
  ]
96
};
97

98
// With minification for production
99
export default {
100
  plugins: [
101
    esbuild({
102
      minify: process.env.NODE_ENV === "production",
103
      target: "es2017",
104
      sourceMap: true
105
    })
106
  ]
107
};
108

109
// Custom JSX configuration
110
export default {
111
  plugins: [
112
    esbuild({
113
      jsx: "transform",
114
      jsxFactory: "h",
115
      jsxFragment: "Fragment"
116
    })
117
  ]
118
};
119

120
// With custom loaders
121
export default {
122
  plugins: [
123
    esbuild({
124
      loaders: {
125
        ".json": "json",
126
        ".js": "jsx" // Enable JSX in .js files
127
      }
128
    })
129
  ]
130
};
131

132
// With dependency optimization
133
export default {
134
  plugins: [
135
    esbuild({
136
      optimizeDeps: {
137
        include: ["react", "react-dom"]
138
      }
139
    })
140
  ]
141
};
142
```
143

144
### File Filtering Options
145

146
Configure which files the plugin should process.
147

148
```typescript { .api }
149
interface FilterOptions {
150
  /** Files to include for processing */
151
  include?: FilterPattern;
152
  /** Files to exclude from processing */
153
  exclude?: FilterPattern;
154
}
155

156
type FilterPattern = string | RegExp | (string | RegExp)[];
157
```
158

159
**Default behavior:**
160
- `include`: `/\.[jt]sx?$/` (matches .js, .jsx, .ts, .tsx files)
161
- `exclude`: `/node_modules/`
162

163
### TypeScript Configuration
164

165
Control how TypeScript configuration is handled.
166

167
```typescript { .api }
168
interface TypeScriptOptions {
169
  /** Path to tsconfig.json file, or false to disable */
170
  tsconfig?: string | false;
171
}
172
```
173

174
**Default behavior:**
175
- Automatically detects `tsconfig.json` in the project
176
- Inherits JSX settings, target, and other compiler options
177
- Set to `false` to disable TypeScript configuration inheritance
178

179
### Custom Loaders
180

181
Configure file type processing with custom loaders.
182

183
```typescript { .api }
184
interface LoaderOptions {
185
  /** Map file extensions to esbuild loaders */
186
  loaders?: { [ext: string]: Loader | false };
187
}
188

189
type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "text" | "base64" | "binary" | "dataurl";
190
```
191

192
**Usage:**
193
```typescript
194
{
195
  loaders: {
196
    ".json": "json",      // Process JSON files
197
    ".js": "jsx",         // Enable JSX in .js files  
198
    ".txt": "text",       // Load text files as strings
199
    ".css": false         // Disable processing for CSS files
200
  }
201
}
202
```
203

204
### JSX Configuration
205

206
Configure JSX transformation behavior.
207

208
```typescript { .api }
209
interface JSXOptions {
210
  /** JSX transformation mode */
211
  jsx?: "transform" | "preserve" | "automatic";
212
  /** JSX factory function name */
213
  jsxFactory?: string;
214
  /** JSX fragment function name */
215
  jsxFragment?: string;
216
  /** Import source for automatic JSX runtime */
217
  jsxImportSource?: string;
218
  /** Enable JSX development mode with additional runtime checks */
219
  jsxDev?: boolean;
220
}
221
```
222

223
**Examples:**
224
```typescript
225
// React classic runtime
226
{
227
  jsx: "transform",
228
  jsxFactory: "React.createElement",
229
  jsxFragment: "React.Fragment"
230
}
231

232
// React automatic runtime
233
{
234
  jsx: "automatic",
235
  jsxImportSource: "react"
236
}
237

238
// Preact
239
{
240
  jsx: "transform", 
241
  jsxFactory: "h",
242
  jsxFragment: "Fragment"
243
}
244
```
245

246
### Minification Options
247

248
Configure code minification behavior.
249

250
```typescript { .api }
251
interface MinificationOptions {
252
  /** Enable full minification */
253
  minify?: boolean;
254
  /** Minify whitespace only */
255
  minifyWhitespace?: boolean;
256
  /** Minify identifiers only */
257
  minifyIdentifiers?: boolean;
258
  /** Minify syntax only */
259
  minifySyntax?: boolean;
260
  /** Preserve function/class names */
261
  keepNames?: boolean;
262
  /** Handle legal comments */
263
  legalComments?: "none" | "inline" | "eof" | "linked" | "external";
264
  /** Drop console statements and debugger */
265
  drop?: ("console" | "debugger")[];
266
  /** Drop labeled statements */
267
  dropLabels?: string[];
268
}
269
```
270

271
### Code Transformation Options
272

273
Configure various code transformation behaviors.
274

275
```typescript { .api }
276
interface TransformationOptions {
277
  /** Compilation target */
278
  target?: string | string[];
279
  /** Global variable replacements */
280
  define?: { [key: string]: string };
281
  /** Output character encoding */
282
  charset?: "ascii" | "utf8";
283
  /** Enable tree shaking */
284
  treeShaking?: boolean;
285
  /** Ignore @__PURE__ annotations */
286
  ignoreAnnotations?: boolean;
287
  /** Output format for standalone builds */
288
  format?: "iife" | "cjs" | "esm";
289
  /** Global name for IIFE format */
290
  globalName?: string;
291
}
292
```
293

294
**Examples:**
295
```typescript
296
{
297
  target: ["es2020", "chrome80"],
298
  define: {
299
    "process.env.NODE_ENV": '"production"',
300
    "__VERSION__": '"1.0.0"'
301
  },
302
  format: "esm",
303
  charset: "utf8"
304
}
305
```