0
# Uppy Core
1

2
Uppy Core is the foundational module for Uppy, a modern, modular JavaScript file uploader that integrates seamlessly with any application. It provides the main Uppy class that manages file uploads, plugins, and state, serving as the central hub for the entire Uppy ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @uppy/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uppy/core`
10

11
## Core Imports
12

13
```typescript
14
import Uppy from "@uppy/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Uppy = require("@uppy/core");
21
```
22

23
Additional exports:
24

25
```typescript
26
import { BasePlugin, UIPlugin, EventManager, debugLogger } from "@uppy/core";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import Uppy from "@uppy/core";
33

34
// Create Uppy instance
35
const uppy = new Uppy({
36
  debug: true,
37
  autoProceed: false,
38
  restrictions: {
39
    maxFileSize: 1000000, // 1MB
40
    maxNumberOfFiles: 5,
41
    allowedFileTypes: ['image/*', 'video/*']
42
  }
43
});
44

45
// Add files
46
uppy.addFile({
47
  name: 'example.jpg',
48
  type: 'image/jpeg',
49
  data: fileBlob,
50
});
51

52
// Listen to events
53
uppy.on('file-added', (file) => {
54
  console.log('Added file:', file.name);
55
});
56

57
uppy.on('upload-success', (file, response) => {
58
  console.log('Upload completed:', file.name);
59
});
60

61
// Start upload
62
uppy.upload().then((result) => {
63
  console.log('Upload result:', result);
64
});
65
```
66

67
## Architecture
68

69
Uppy Core is built around several key architectural components:
70

71
- **State Management**: Centralized state store with immutable updates and event notifications
72
- **Plugin System**: Extensible architecture supporting both UI and non-UI plugins via BasePlugin/UIPlugin
73
- **Event System**: Comprehensive event emitter with typed events for all lifecycle stages
74
- **File Management**: Complete file lifecycle from addition through upload with metadata and validation
75
- **Processing Pipeline**: Pre-processors, uploaders, and post-processors for flexible upload workflows
76
- **Restriction Engine**: Configurable file validation with individual and aggregate restrictions
77

78
## Capabilities
79

80
### Core Uppy Class
81

82
Main class providing file upload management, state management, plugin system, and event handling. The central component that orchestrates all upload operations.
83

84
```typescript { .api }
85
class Uppy<M extends Meta = Meta, B extends Body = Record<string, never>> {
86
  static VERSION: string;
87
  constructor(opts?: UppyOptions<M, B>);
88
  
89
  // State management
90
  getState(): State<M, B>;
91
  setState(patch?: Partial<State<M, B>>): void;
92
  
93
  // File management
94
  addFile(file: File | MinimalRequiredUppyFile<M, B>): string;
95
  addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void;
96
  removeFile(fileID: string): void;
97
  getFile(fileID: string): UppyFile<M, B>;
98
  getFiles(): UppyFile<M, B>[];
99
  
100
  // Upload control
101
  upload(): Promise<UploadResult<M, B> | undefined>;
102
  pauseResume(fileID: string): boolean | undefined;
103
  pauseAll(): void;
104
  resumeAll(): void;
105
  retryAll(): Promise<UploadResult<M, B> | undefined>;
106
  cancelAll(): void;
107
}
108
```
109

110
[Core Uppy Class](./uppy-class.md)
111

112
### Plugin Development
113

114
Base classes for creating Uppy plugins, providing foundation for both UI and non-UI plugins with state management, localization, and lifecycle hooks.
115

116
```typescript { .api }
117
abstract class BasePlugin<
118
  Opts extends PluginOpts,
119
  M extends Meta,
120
  B extends Body,
121
  PluginState extends Record<string, unknown> = Record<string, unknown>
122
> {
123
  uppy: Uppy<M, B>;
124
  opts: Opts;
125
  id: string;
126
  
127
  constructor(uppy: Uppy<M, B>, opts?: Opts);
128
  getPluginState(): PluginState;
129
  setPluginState(update?: Partial<PluginState>): void;
130
  setOptions(newOpts: Partial<Opts>): void;
131
  
132
  // Lifecycle hooks
133
  install(): void;
134
  uninstall(): void;
135
  update(state: Partial<State<M, B>>): void;
136
  afterUpdate(): void;
137
}
138

139
abstract class UIPlugin<
140
  Opts extends UIPluginOptions,
141
  M extends Meta,
142
  B extends Body,
143
  PluginState extends Record<string, unknown> = Record<string, unknown>
144
> extends BasePlugin<Opts, M, B, PluginState> {
145
  render(): ComponentChild;
146
  mount(target: PluginTarget, plugin: UnknownPlugin<M, B>): void;
147
  unmount(): void;
148
}
149
```
150

151
[Plugin Development](./plugin-development.md)
152

153
### Event Management
154

155
Comprehensive event system for handling upload lifecycle events, with both global and file-specific event handling capabilities.
156

157
```typescript { .api }
158
class EventManager<M extends Meta, B extends Body> {
159
  constructor(uppy: Uppy<M, B>);
160
  
161
  on<K extends keyof UppyEventMap<M, B>>(
162
    event: K,
163
    fn: UppyEventMap<M, B>[K]
164
  ): Uppy<M, B>;
165
  
166
  remove(): void;
167
  
168
  // File-specific event helpers
169
  onFilePause(fileID: string, cb: (isPaused: boolean) => void): void;
170
  onFileRemove(fileID: string, cb: (fileID: string) => void): void;
171
  onRetry(fileID: string, cb: () => void): void;
172
}
173
```
174

175
[Event Management](./event-management.md)
176

177
### File Validation and Restrictions
178

179
Configurable file validation system supporting both individual file restrictions and aggregate restrictions across all files.
180

181
```typescript { .api }
182
interface Restrictions {
183
  maxFileSize: number | null;
184
  minFileSize: number | null;
185
  maxTotalFileSize: number | null;
186
  maxNumberOfFiles: number | null;
187
  minNumberOfFiles: number | null;
188
  allowedFileTypes: string[] | null;
189
  requiredMetaFields: string[];
190
}
191

192
class RestrictionError<M extends Meta, B extends Body> extends Error {
193
  isUserFacing: boolean;
194
  file?: UppyFile<M, B>;
195
  isRestriction: true;
196
}
197
```
198

199
[File Validation](./file-validation.md)
200

201
### Type System
202

203
Complete TypeScript type definitions for customizing file metadata, body types, and ensuring type safety throughout the upload process.
204

205
```typescript { .api }
206
interface UppyFile<M extends Meta = Meta, B extends Body = Body> {
207
  id: string;
208
  name: string;
209
  type: string;
210
  size: number;
211
  data: File | B;
212
  meta: M;
213
  source: string;
214
  progress?: FileProgress;
215
  response?: {
216
    status: number;
217
    body: any;
218
    uploadURL?: string;
219
  };
220
}
221

222
interface UppyOptions<M extends Meta = Meta, B extends Body = Body> {
223
  id?: string;
224
  autoProceed?: boolean;
225
  allowMultipleUploadBatches?: boolean;
226
  debug?: boolean;
227
  restrictions?: Partial<Restrictions>;
228
  meta?: Partial<M>;
229
  locale?: Locale;
230
  store?: Store;
231
  logger?: typeof debugLogger;
232
  infoTimeout?: number;
233
  onBeforeFileAdded?: (
234
    currentFile: UppyFile<M, B>,
235
    files: { [key: string]: UppyFile<M, B> }
236
  ) => boolean | Promise<boolean>;
237
  onBeforeUpload?: (
238
    files: { [key: string]: UppyFile<M, B> }
239
  ) => boolean | Promise<boolean>;
240
}
241
```
242

243
[Type System](./type-system.md)