0
# Utility Plugins
1

2
Utility plugins provide supporting functionality including file processing, state management, form integration, crash recovery, and development tools.
3

4
## Capabilities
5

6
### File Processing Utilities
7

8
Plugins that process files and generate additional metadata or assets.
9

10
```typescript { .api }
11
/**
12
 * Thumbnail generator for image and video previews
13
 */
14
class ThumbnailGenerator<M extends Meta = {}, B extends Body = {}> extends BasePlugin<ThumbnailGeneratorOptions> {
15
  constructor(uppy: Uppy<M, B>, options?: ThumbnailGeneratorOptions);
16
}
17

18
interface ThumbnailGeneratorOptions {
19
  thumbnailWidth?: number;
20
  thumbnailHeight?: number;
21
  thumbnailType?: string;
22
  thumbnailQuality?: number;
23
  waitForThumbnailsBeforeUpload?: boolean;
24
  lazy?: boolean;
25
  locale?: Locale;
26
}
27
```
28

29
**Usage Example:**
30

31
```typescript
32
import { Uppy, ThumbnailGenerator } from "uppy";
33

34
const uppy = new Uppy()
35
  .use(ThumbnailGenerator, {
36
    thumbnailWidth: 300,
37
    thumbnailHeight: 300,
38
    thumbnailType: 'image/jpeg',
39
    thumbnailQuality: 0.8,
40
    waitForThumbnailsBeforeUpload: false,
41
    lazy: true // Generate thumbnails only when needed
42
  });
43

44
// Listen for thumbnail generation
45
uppy.on('thumbnail:generated', (file, preview) => {
46
  console.log('Thumbnail generated for:', file.name);
47
  // Display preview in UI
48
  const img = document.querySelector(`[data-file-id="${file.id}"] img`);
49
  if (img) {
50
    img.src = preview;
51
  }
52
});
53
```
54

55
### State Management and Recovery
56

57
Plugins for managing upload state and recovering from interruptions.
58

59
```typescript { .api }
60
/**
61
 * Golden Retriever for crash recovery and file restoration
62
 */
63
class GoldenRetriever<M extends Meta = {}, B extends Body = {}> extends BasePlugin<GoldenRetrieverOptions> {
64
  constructor(uppy: Uppy<M, B>, options?: GoldenRetrieverOptions);
65
}
66

67
interface GoldenRetrieverOptions {
68
  expires?: number;
69
  serviceWorker?: boolean;
70
  indexedDB?: {
71
    maxFileSize?: number;
72
    maxTotalSize?: number;
73
  };
74
  locale?: Locale;
75
}
76

77
/**
78
 * Redux DevTools integration for debugging
79
 */
80
class ReduxDevTools<M extends Meta = {}, B extends Body = {}> extends BasePlugin<any> {
81
  constructor(uppy: Uppy<M, B>, options?: any);
82
}
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
// Golden Retriever for crash recovery
89
uppy.use(GoldenRetriever, {
90
  expires: 24 * 60 * 60 * 1000, // 24 hours
91
  serviceWorker: true,
92
  indexedDB: {
93
    maxFileSize: 50 * 1024 * 1024, // 50MB per file
94
    maxTotalSize: 200 * 1024 * 1024 // 200MB total
95
  }
96
});
97

98
// Redux DevTools for debugging (development only)
99
if (process.env.NODE_ENV === 'development') {
100
  uppy.use(ReduxDevTools);
101
}
102
```
103

104
### Form Integration
105

106
Plugins that integrate Uppy with HTML forms and collect metadata.
107

108
```typescript { .api }
109
/**
110
 * Form integration for metadata collection and submission
111
 */
112
class Form<M extends Meta = {}, B extends Body = {}> extends BasePlugin<FormOptions> {
113
  constructor(uppy: Uppy<M, B>, options?: FormOptions);
114
}
115

116
interface FormOptions {
117
  target?: string | HTMLFormElement;
118
  resultName?: string;
119
  getMetaFromForm?: boolean;
120
  addResultToForm?: boolean;
121
  multipleResults?: boolean;
122
  submitOnSuccess?: boolean;
123
  triggerUploadOnSubmit?: boolean;
124
  locale?: Locale;
125
}
126
```
127

128
**Usage Example:**
129

130
```typescript
131
// Form integration
132
uppy.use(Form, {
133
  target: '#upload-form',
134
  resultName: 'uppyResult',
135
  getMetaFromForm: true,
136
  addResultToForm: true,
137
  submitOnSuccess: true,
138
  triggerUploadOnSubmit: true
139
});
140

141
// The form will collect metadata from form fields
142
// and submit automatically after successful upload
143
```
144

145
### State Store Plugins
146

147
Alternative state management implementations.
148

149
```typescript { .api }
150
/**
151
 * Default state store implementation
152
 */
153
class DefaultStore<M extends Meta = {}, B extends Body = {}> extends BasePlugin<any> {
154
  constructor(uppy: Uppy<M, B>, options?: any);
155
}
156

157
/**
158
 * Redux store integration for state management
159
 */
160
class ReduxStore<M extends Meta = {}, B extends Body = {}> extends BasePlugin<ReduxStoreOptions> {
161
  constructor(uppy: Uppy<M, B>, options?: ReduxStoreOptions);
162
}
163

164
interface ReduxStoreOptions {
165
  store: any; // Redux store instance
166
  id?: string;
167
  selector?: (state: any) => any;
168
}
169
```
170

171
**Usage Example:**
172

173
```typescript
174
import { createStore } from 'redux';
175
import { ReduxStore } from 'uppy';
176

177
// Create Redux store
178
const store = createStore(rootReducer);
179

180
// Use Redux store with Uppy
181
const uppy = new Uppy({
182
  store: ReduxStore,
183
  id: 'uppy',
184
  selector: (state) => state.uppy
185
});
186
```
187

188
### Development and Debugging
189

190
Tools for development, debugging, and monitoring.
191

192
```typescript { .api }
193
/**
194
 * Debug logger utility
195
 */
196
interface DebugLogger {
197
  debug(...args: any[]): void;
198
  info(...args: any[]): void;
199
  warn(...args: any[]): void;
200
  error(...args: any[]): void;
201
}
202

203
/**
204
 * Create debug logger instance
205
 */
206
function debugLogger(namespace?: string): DebugLogger;
207
```
208

209
**Usage Example:**
210

211
```typescript
212
import { debugLogger } from 'uppy';
213

214
// Create namespaced logger
215
const logger = debugLogger('MyApp');
216

217
// Use logger in plugin or application
218
logger.info('Uppy initialized');
219
logger.warn('File size exceeds limit');
220
logger.error('Upload failed', error);
221

222
// Enable debug logging in browser console
223
localStorage.setItem('debug', 'uppy:*');
224
```
225

226
## Utility Plugin Events
227

228
```typescript { .api }
229
// Thumbnail generation events
230
interface ThumbnailEvents<M extends Meta = {}, B extends Body = {}> {
231
  'thumbnail:generated': (file: UppyFile<M, B>, preview: string) => void;
232
  'thumbnail:error': (file: UppyFile<M, B>, error: Error) => void;
233
}
234

235
// Golden Retriever events
236
interface GoldenRetrieverEvents {
237
  'restored': () => void; 
238
}
239

240
// Form integration events
241
interface FormEvents {
242
  'form:submit': (formData: FormData) => void;
243
  'form:meta-collected': (meta: { [key: string]: any }) => void;
244
}
245
```
246

247
## Configuration Interfaces
248

249
```typescript { .api }
250
/**
251
 * Common utility plugin options
252
 */
253
interface BaseUtilityOptions {
254
  locale?: Locale;
255
}
256

257
/**
258
 * File processing options
259
 */
260
interface FileProcessingOptions {
261
  waitForProcessingBeforeUpload?: boolean;
262
  processInBackground?: boolean;
263
  processingTimeout?: number;
264
}
265

266
/**
267
 * Storage configuration for persistent plugins
268
 */
269
interface StorageConfig {
270
  provider: 'localStorage' | 'sessionStorage' | 'indexedDB' | 'memory';
271
  key?: string;
272
  expires?: number;
273
  maxSize?: number;
274
}
275

276
/**
277
 * Metadata collection configuration
278
 */
279
interface MetadataCollectionOptions {
280
  collectFromForm?: boolean;
281
  formSelector?: string;
282
  fieldMapping?: { [formField: string]: string };
283
  requiredFields?: string[];
284
  validateMetadata?: (meta: any) => boolean | string;
285
}
286
```
287

288
## Performance and Optimization
289

290
```typescript { .api }
291
/**
292
 * Performance monitoring utilities
293
 */
294
interface PerformanceMonitor {
295
  startTimer(label: string): void;
296
  endTimer(label: string): number;
297
  measureMemory(): number;
298
  getMetrics(): PerformanceMetrics;
299
}
300

301
interface PerformanceMetrics {
302
  uploadTime: number;
303
  processingTime: number;
304
  memoryUsage: number;
305
  filesProcessed: number;
306
  bytesUploaded: number;
307
}
308

309
/**
310
 * Resource optimization options
311
 */
312
interface OptimizationOptions {
313
  enableWorkers?: boolean;
314
  maxConcurrentUploads?: number;
315
  chunkSize?: number;
316
  memoryLimit?: number;
317
  diskCacheEnabled?: boolean;
318
}
319
```