or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

event-management.mdfile-validation.mdindex.mdplugin-development.mdtype-system.mduppy-class.md
tile.json

tessl/npm-uppy--core

Core module for the extensible JavaScript file upload widget with support for drag&drop, resumable uploads, previews, restrictions, file processing/encoding, remote providers like Instagram, Dropbox, Google Drive, S3 and more

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@uppy/core@5.0.x

To install, run

npx @tessl/cli install tessl/npm-uppy--core@5.0.0

index.mddocs/

Uppy Core

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.

Package Information

  • Package Name: @uppy/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @uppy/core

Core Imports

import Uppy from "@uppy/core";

For CommonJS:

const Uppy = require("@uppy/core");

Additional exports:

import { BasePlugin, UIPlugin, EventManager, debugLogger } from "@uppy/core";

Basic Usage

import Uppy from "@uppy/core";

// Create Uppy instance
const uppy = new Uppy({
  debug: true,
  autoProceed: false,
  restrictions: {
    maxFileSize: 1000000, // 1MB
    maxNumberOfFiles: 5,
    allowedFileTypes: ['image/*', 'video/*']
  }
});

// Add files
uppy.addFile({
  name: 'example.jpg',
  type: 'image/jpeg',
  data: fileBlob,
});

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

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

// Start upload
uppy.upload().then((result) => {
  console.log('Upload result:', result);
});

Architecture

Uppy Core is built around several key architectural components:

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

Capabilities

Core Uppy Class

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

class Uppy<M extends Meta = Meta, B extends Body = Record<string, never>> {
  static VERSION: string;
  constructor(opts?: UppyOptions<M, B>);
  
  // State management
  getState(): State<M, B>;
  setState(patch?: Partial<State<M, B>>): void;
  
  // File management
  addFile(file: File | MinimalRequiredUppyFile<M, B>): string;
  addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void;
  removeFile(fileID: string): void;
  getFile(fileID: string): UppyFile<M, B>;
  getFiles(): UppyFile<M, B>[];
  
  // Upload control
  upload(): Promise<UploadResult<M, B> | undefined>;
  pauseResume(fileID: string): boolean | undefined;
  pauseAll(): void;
  resumeAll(): void;
  retryAll(): Promise<UploadResult<M, B> | undefined>;
  cancelAll(): void;
}

Core Uppy Class

Plugin Development

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

abstract class BasePlugin<
  Opts extends PluginOpts,
  M extends Meta,
  B extends Body,
  PluginState extends Record<string, unknown> = Record<string, unknown>
> {
  uppy: Uppy<M, B>;
  opts: Opts;
  id: string;
  
  constructor(uppy: Uppy<M, B>, opts?: Opts);
  getPluginState(): PluginState;
  setPluginState(update?: Partial<PluginState>): void;
  setOptions(newOpts: Partial<Opts>): void;
  
  // Lifecycle hooks
  install(): void;
  uninstall(): void;
  update(state: Partial<State<M, B>>): void;
  afterUpdate(): void;
}

abstract class UIPlugin<
  Opts extends UIPluginOptions,
  M extends Meta,
  B extends Body,
  PluginState extends Record<string, unknown> = Record<string, unknown>
> extends BasePlugin<Opts, M, B, PluginState> {
  render(): ComponentChild;
  mount(target: PluginTarget, plugin: UnknownPlugin<M, B>): void;
  unmount(): void;
}

Plugin Development

Event Management

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

class EventManager<M extends Meta, B extends Body> {
  constructor(uppy: Uppy<M, B>);
  
  on<K extends keyof UppyEventMap<M, B>>(
    event: K,
    fn: UppyEventMap<M, B>[K]
  ): Uppy<M, B>;
  
  remove(): void;
  
  // File-specific event helpers
  onFilePause(fileID: string, cb: (isPaused: boolean) => void): void;
  onFileRemove(fileID: string, cb: (fileID: string) => void): void;
  onRetry(fileID: string, cb: () => void): void;
}

Event Management

File Validation and Restrictions

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

interface Restrictions {
  maxFileSize: number | null;
  minFileSize: number | null;
  maxTotalFileSize: number | null;
  maxNumberOfFiles: number | null;
  minNumberOfFiles: number | null;
  allowedFileTypes: string[] | null;
  requiredMetaFields: string[];
}

class RestrictionError<M extends Meta, B extends Body> extends Error {
  isUserFacing: boolean;
  file?: UppyFile<M, B>;
  isRestriction: true;
}

File Validation

Type System

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

interface UppyFile<M extends Meta = Meta, B extends Body = Body> {
  id: string;
  name: string;
  type: string;
  size: number;
  data: File | B;
  meta: M;
  source: string;
  progress?: FileProgress;
  response?: {
    status: number;
    body: any;
    uploadURL?: string;
  };
}

interface UppyOptions<M extends Meta = Meta, B extends Body = Body> {
  id?: string;
  autoProceed?: boolean;
  allowMultipleUploadBatches?: boolean;
  debug?: boolean;
  restrictions?: Partial<Restrictions>;
  meta?: Partial<M>;
  locale?: Locale;
  store?: Store;
  logger?: typeof debugLogger;
  infoTimeout?: number;
  onBeforeFileAdded?: (
    currentFile: UppyFile<M, B>,
    files: { [key: string]: UppyFile<M, B> }
  ) => boolean | Promise<boolean>;
  onBeforeUpload?: (
    files: { [key: string]: UppyFile<M, B> }
  ) => boolean | Promise<boolean>;
}

Type System