0
# Dependency Optimization
1

2
The experimental dependency optimization feature provides pre-bundling capabilities for external dependencies using esbuild's fast bundling engine, eliminating the need for additional CommonJS and Node.js resolution plugins.
3

4
## Capabilities
5

6
### Dependency Optimization Configuration
7

8
Configure which dependencies should be pre-bundled and optimized during the build process.
9

10
```typescript { .api }
11
interface OptimizeDepsOptions {
12
  /** List of dependency names to include in optimization */
13
  include: string[];
14
  /** List of dependency names to exclude from optimization */
15
  exclude?: string[];
16
  /** Working directory for dependency resolution */
17
  cwd: string;
18
  /** Additional esbuild options for the optimization build */
19
  esbuildOptions?: EsbuildBuildOptions;
20
  /** Enable source map generation for optimized dependencies */
21
  sourceMap: boolean;
22
}
23

24
interface OptimizeDepsResult {
25
  /** Map of optimized dependencies to their bundled file paths */
26
  optimized: Map<string, { file: string }>;
27
  /** Directory where optimized dependencies are cached */
28
  cacheDir: string;
29
}
30

31
// Re-exported from esbuild for reference
32
interface EsbuildBuildOptions {
33
  entryPoints?: string[];
34
  bundle?: boolean;
35
  splitting?: boolean;
36
  format?: "iife" | "cjs" | "esm";
37
  target?: string | string[];
38
  outdir?: string;
39
  outfile?: string;
40
  platform?: "browser" | "node" | "neutral";
41
  external?: string[];
42
  loader?: { [ext: string]: Loader };
43
  define?: { [key: string]: string };
44
  inject?: string[];
45
  banner?: { [type: string]: string };
46
  footer?: { [type: string]: string };
47
  metafile?: boolean;
48
  write?: boolean;
49
  plugins?: any[];
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import esbuild from "rollup-plugin-esbuild";
57

58
// Basic dependency optimization
59
export default {
60
  plugins: [
61
    esbuild({
62
      optimizeDeps: {
63
        include: ["react", "react-dom"]
64
      }
65
    })
66
  ]
67
};
68

69
// Advanced optimization with exclusions
70
export default {
71
  plugins: [
72
    esbuild({
73
      optimizeDeps: {
74
        include: ["lodash", "moment", "axios"],
75
        exclude: ["moment/locale/*"],
76
        esbuildOptions: {
77
          target: "es2020",
78
          format: "esm"
79
        }
80
      }
81
    })
82
  ]
83
};
84

85
// Optimization with custom esbuild options
86
export default {
87
  plugins: [
88
    esbuild({
89
      optimizeDeps: {
90
        include: ["vue", "vue-router"],
91
        esbuildOptions: {
92
          define: {
93
            "process.env.NODE_ENV": '"production"'
94
          },
95
          external: ["node:*"]
96
        }
97
      }
98
    })
99
  ]
100
};
101
```
102

103
### Include Dependencies
104

105
Specify which dependencies should be optimized and pre-bundled.
106

107
```typescript { .api }
108
interface IncludeOptions {
109
  /** Array of dependency names to optimize */
110
  include: string[];
111
}
112
```
113

114
**Behavior:**
115
- Dependencies are resolved from `node_modules`
116
- Each dependency is bundled into a single optimized file
117
- Optimized files are cached in `node_modules/.optimize_deps`
118
- Supports both bare module names and scoped packages
119

120
**Examples:**
121
```typescript
122
{
123
  include: [
124
    "react",              // Regular package
125
    "react-dom",          
126
    "@babel/core",        // Scoped package
127
    "lodash/debounce"     // Specific export
128
  ]
129
}
130
```
131

132
### Exclude Dependencies
133

134
Specify dependencies that should be excluded from optimization even if they're dependencies of included packages.
135

136
```typescript { .api }
137
interface ExcludeOptions {
138
  /** Array of dependency names to exclude from optimization */
139
  exclude?: string[];
140
}
141
```
142

143
**Usage:**
144
```typescript
145
{
146
  include: ["react", "react-dom"],
147
  exclude: [
148
    "react-dom/server",   // Exclude server-side rendering
149
    "react/jsx-dev-runtime" // Exclude development runtime
150
  ]
151
}
152
```
153

154
### Cache Directory
155

156
The optimization process creates a cache directory for optimized dependencies.
157

158
```typescript { .api }
159
interface CacheInfo {
160
  /** Default cache directory location */
161
  cacheDir: string; // "node_modules/.optimize_deps"
162
}
163
```
164

165
**Behavior:**
166
- Cache directory is automatically created
167
- Contains bundled versions of optimized dependencies
168
- Files are named after the dependency (e.g., `react.js`, `vue.js`)
169
- Cache is persistent across builds for performance
170

171
### Custom ESBuild Options
172

173
Provide additional esbuild configuration for the optimization build process.
174

175
```typescript { .api }
176
interface OptimizationBuildOptions {
177
  /** Additional esbuild options for optimization */
178
  esbuildOptions?: {
179
    /** Target environment for optimized code */
180
    target?: string | string[];
181
    /** Output format for optimized bundles */
182
    format?: "esm" | "cjs";
183
    /** Global replacements for optimized code */
184
    define?: { [key: string]: string };
185
    /** External dependencies that shouldn't be bundled */
186
    external?: string[];
187
    /** Custom loaders for specific file types */
188
    loader?: { [ext: string]: Loader };
189
    /** Code injection for polyfills or setup */
190
    inject?: string[];
191
    /** Platform-specific optimizations */
192
    platform?: "browser" | "node" | "neutral";
193
  };
194
}
195
```
196

197
**Common configurations:**
198
```typescript
199
// Browser-optimized dependencies
200
{
201
  esbuildOptions: {
202
    target: ["es2020", "chrome80"],
203
    format: "esm",
204
    platform: "browser",
205
    define: {
206
      "process.env.NODE_ENV": '"production"'
207
    }
208
  }
209
}
210

211
// Node.js optimized dependencies
212
{
213
  esbuildOptions: {
214
    target: "node16",
215
    format: "cjs",
216
    platform: "node",
217
    external: ["node:*"]
218
  }
219
}
220
```
221

222
### Integration with Rollup Build
223

224
The optimization integrates seamlessly with the Rollup build process through plugin lifecycle hooks.
225

226
```typescript { .api }
227
interface OptimizationLifecycle {
228
  /** Runs during buildStart phase */
229
  buildStart(): Promise<void>;
230
  /** Intercepts module resolution */
231
  resolveId(id: string, importer?: string): string | null;
232
}
233
```
234

235
**Behavior:**
236
- Optimization runs once during `buildStart`
237
- Optimized dependencies are resolved to their cached versions
238
- No changes required to import statements in source code
239
- Works transparently with existing Rollup configuration
240

241
### Performance Benefits
242

243
Dependency optimization provides several performance improvements:
244

245
**Build Time Benefits:**
246
- Pre-bundled dependencies reduce individual file processing
247
- Eliminates need for CommonJS transformation of dependencies
248
- Reduces module resolution overhead during build
249

250
**Runtime Benefits:**
251
- Fewer HTTP requests for dependency files
252
- Optimized and minified dependency code
253
- Better tree-shaking of unused dependency code
254

255
**Bundle Size Benefits:**
256
- Dead code elimination across dependency boundaries
257
- Optimized imports and exports
258
- Reduced duplication between dependencies
259

260
### Limitations and Considerations
261

262
**Experimental Status:**
263
- Feature is marked as experimental
264
- Breaking changes may occur in minor versions
265
- Not recommended for production use without thorough testing
266

267
**Compatibility:**
268
- Some packages may not work correctly when pre-bundled
269
- Dynamic imports within dependencies may be affected
270
- Native Node.js modules cannot be optimized
271

272
**Troubleshooting:**
273
- Use `exclude` option for problematic dependencies
274
- Check generated cache files for bundling issues
275
- Monitor build output for optimization warnings