Required dependencies

npm install @uppy/core @uppy/dashboard @uppy/tus @uppy/xhr-upload
npm install @uppy/aws-s3 @uppy/companion-client
npm install @uppy/webcam @uppy/audio @uppy/screen-capture
npm install @uppy/image-editor @uppy/thumbnail-generator @uppy/compressor
npm install @uppy/drag-drop @uppy/drop-target @uppy/status-bar
npm install @uppy/remote-sources @uppy/transloadit
npm install @uppy/google-drive @uppy/dropbox @uppy/box @uppy/onedrive
npm install @uppy/instagram @uppy/facebook @uppy/unsplash @uppy/url
npm install @uppy/form @uppy/golden-retriever
npm install @uppy/react        # if using React
npm install @uppy/vue          # if using Vue
npm install @uppy/svelte       # if using Svelte
# Angular: see angular/ directory; install via ng add or the package.json inside angular/
npm install tus-js-client      # peer dep for @uppy/tus
npm install @aws-sdk/client-s3 # peer dep for @uppy/aws-s3 presigned URL helpers

No native modules, pod install, or Android linking steps are required. This is a pure JS/TS package.

Project setup

1. Copy the source/ directory into your project, e.g. as packages/@uppy/, or install packages directly from npm as shown above.
2. If using the local source tree, add path aliases to tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@uppy/core": ["./packages/@uppy/core/src/index.ts"],
      "@uppy/dashboard": ["./packages/@uppy/dashboard/src/index.ts"],
      "@uppy/tus": ["./packages/@uppy/tus/src/index.ts"]
    },
    "moduleResolution": "bundler",
    "target": "ES2020",
    "module": "ESNext"
  }
}

3. If using a bundler (Vite, Webpack), ensure .js extension imports resolve to TypeScript sources, or use the published npm packages instead.
4. For @uppy/companion (server-side), add to your Express app and set environment variables:

COMPANION_SECRET=your_secret_here
COMPANION_DOMAIN=https://your-domain.com
COMPANION_PROTOCOL=https

5. Import CSS for Dashboard (required for default styling):

import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'

Public API

default (Uppy core class)

import Uppy from '@uppy/core'
const uppy = new Uppy({ id: 'uppy', autoProceed: false })

The central orchestrator. Instantiate once per upload flow. Call .use(Plugin, opts) to attach plugins, .upload() to start, and .on('complete', handler) to receive results.

default (AudioOscilloscope)

import AudioOscilloscope from '@uppy/audio/src/audio-oscilloscope/index.ts'

const oscilloscope = new AudioOscilloscope(canvasElement, {
  canvas: { width: 300, height: 100 },
  canvasContext: { lineWidth: 2, strokeStyle: '#000' },
  onDrawFrame: (osc) => { /* custom draw */ },
})

Visualizes a live audio stream on a <canvas>. Attach a MediaStream source and call draw() to animate. Used internally by @uppy/audio but can be used standalone.

AwsS3Multipart (from aws-s3/src/index.ts)

import AwsS3Multipart from '@uppy/aws-s3'
import type { AwsS3MultipartOptions } from '@uppy/aws-s3'

uppy.use(AwsS3Multipart, {
  shouldUseMultipart: (file) => file.size > 100 * 1024 * 1024,
  getUploadParameters: async (file) => {
    const res = await fetch('/presign', { method: 'POST', body: JSON.stringify({ filename: file.name }) })
    return res.json()
  },
})

Handles both single-part and multipart S3-compatible uploads. Emits s3-multipart:part-uploaded events per chunk. Use for large file uploads to AWS S3 or compatible storage (R2, MinIO).

AudioOptions type

import type { AudioOptions } from '@uppy/audio'
const opts: AudioOptions = { showAudioSourceDropdown: true }

TypeScript options type for the Audio plugin. Pass to uppy.use(Audio, opts).

BoxOptions type

import type { BoxOptions } from '@uppy/box'
const opts: BoxOptions = { companionUrl: 'https://companion.uppy.io' }

TypeScript options type for the Box plugin. All remote provider plugins follow the same pattern: companionUrl is the only required option.

Working examples

Scenario - Basic dashboard with tus resumable upload

A standard file upload UI with drag-and-drop, preview, and resumable upload to a tus server.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Tus from '@uppy/tus'
import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'

const uppy = new Uppy({ autoProceed: false })
  .use(Dashboard, {
    inline: true,
    target: '#uppy-container',
    proudlyDisplayPoweredByUppy: false,
  })
  .use(Tus, {
    endpoint: 'https://tusd.tusdemo.net/files/',
    retryDelays: [0, 1000, 3000, 5000],
  })

uppy.on('complete', (result) => {
  console.log('Successful uploads:', result.successful)
  console.log('Failed uploads:', result.failed)
})

uppy.on('upload-error', (file, error) => {
  console.error('Upload error for', file?.name, error)
})

Scenario - S3 multipart upload with presigned URLs

Upload large files directly to S3 using multipart, with presigned URLs generated server-side.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import AwsS3Multipart from '@uppy/aws-s3'

const uppy = new Uppy()
  .use(Dashboard, { inline: true, target: '#uppy' })
  .use(AwsS3Multipart, {
    shouldUseMultipart: (file) => (file.size ?? 0) > 5 * 1024 * 1024,
    async getUploadParameters(file) {
      const response = await fetch('/api/s3/params', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ filename: file.name, contentType: file.type }),
      })
      return response.json() // { url, method, fields, headers }
    },
    async createMultipartUpload(file) {
      const res = await fetch('/api/s3/multipart', {
        method: 'POST',
        body: JSON.stringify({ filename: file.name, type: file.type }),
        headers: { 'content-type': 'application/json' },
      })
      return res.json() // { uploadId, key }
    },
  })

uppy.on('s3-multipart:part-uploaded', (file, part) => {
  console.log(`Part ${part.PartNumber} uploaded for ${file.name}`)
})

Scenario - React integration with webcam and image editor

A React component using Dashboard with Webcam and ImageEditor plugins.

import React, { useEffect } from 'react'
import Uppy from '@uppy/core'
import { Dashboard } from '@uppy/react'
import Webcam from '@uppy/webcam'
import ImageEditor from '@uppy/image-editor'
import XHR from '@uppy/xhr-upload'
import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'
import '@uppy/webcam/dist/style.min.css'
import '@uppy/image-editor/dist/style.min.css'

const uppy = new Uppy()
  .use(Webcam, { modes: ['picture', 'video-audio'] })
  .use(ImageEditor, { quality: 0.8 })
  .use(XHR, { endpoint: '/api/upload' })

export function FileUploader() {
  useEffect(() => {
    return () => uppy.destroy()
  }, [])

  return (
    <Dashboard
      uppy={uppy}
      plugins={['Webcam', 'ImageEditor']}
      height={450}
    />
  )
}

File walkthrough

• core/ - The Uppy class, BasePlugin, EventManager, and all core TypeScript types (Meta, Body, UppyFile, UppyEventMap). Every plugin depends on this.
• dashboard/ - The flagship full-UI plugin. Renders a modal or inline panel with file list, progress bars, and plugin panels.
• aws-s3/ - S3 multipart and single-part upload logic. Exports AwsS3Multipart and related types. Contains MultipartUploader, HTTPCommunicationQueue, and createSignedURL.
• audio/ - Audio recording plugin. Exports AudioOptions type and default Audio plugin. Contains AudioOscilloscope for canvas waveform rendering.
• box/ - Box.com OAuth provider plugin. Exports BoxOptions and default Box class.
• companion/ - Express-based server. Exports controller handlers (callback, connect, get, list, etc.) for OAuth flows and file proxying.
• companion-client/ - Client-side RequestClient base class used by remote provider plugins to communicate with Companion.
• tus/ - Resumable upload plugin wrapping tus-js-client. Handles retry, fingerprinting, and pause/resume.
• xhr-upload/ - Generic multipart form or binary upload via XHR. The simplest upload plugin for custom endpoints.
• transloadit/ - Transloadit Assembly integration. Wraps Tus and adds Assembly creation, status polling, and encoding results.
• image-editor/ - In-browser image editing (crop, rotate, flip, zoom) using cropperjs.
• webcam/ - Webcam and microphone capture plugin. Supports photo, video, and audio modes.
• screen-capture/ - Screen/window/tab recording via getDisplayMedia.
• thumbnail-generator/ - Generates image thumbnails client-side via Canvas API.
• compressor/ - Compresses images before upload using compressorjs.
• remote-sources/ - Convenience plugin that registers Google Drive, Dropbox, Box, Instagram, Facebook, OneDrive, Unsplash, Url, and Zoom simultaneously.
• google-drive/ - Google Drive OAuth file picker.
• google-drive-picker/ - Google Drive Picker API (no Companion required).
• google-photos-picker/ - Google Photos Picker API (no Companion required).
• dropbox/ - Dropbox OAuth file picker.
• instagram/ - Instagram OAuth media picker.
• facebook/ - Facebook OAuth photo picker.
• onedrive/ - Microsoft OneDrive OAuth file picker.
• unsplash/ - Unsplash image search and import.
• url/ - Import a file from an arbitrary URL via Companion.
• zoom/ - Zoom cloud recording picker.
• form/ - Reads form fields and submits them alongside uploads.
• golden-retriever/ - Recovers interrupted uploads across page reloads using IndexedDB and a Service Worker.
• drag-drop/ - Minimal standalone drag-and-drop zone, no full Dashboard UI.
• drop-target/ - Makes any existing DOM element a valid drop target.
• status-bar/ - Compact upload progress and control bar, usable outside Dashboard.
• store-default/ - In-memory state store. Swap for Redux or another store via @uppy/store-redux.
• provider-views/ - Shared React UI (file browser grid/list) used by all remote provider plugins.
• locales/ - Locale packs for every supported language. Import and pass to Uppy({ locale }).
• utils/ - Internal utilities: RateLimitedQueue, filterFilesToUpload, createAbortError, type exports.
• react/ - <Dashboard />, <DragDrop />, <StatusBar />, hooks (useUppyState, useUppyPluginState), and HOCs.
• vue/ - Vue 3 composables and component wrappers.
• svelte/ - Svelte action and component wrappers.
• angular/ - Angular NgModule with DashboardComponent, DashboardModalComponent, StatusBarComponent.
• webdav/ - WebDAV server file picker via Companion.
• image-generator/ - Test utility for generating synthetic Uppy file objects programmatically.
• components/ - Shared headless primitives used across framework adapters.

Common pitfalls and fixes

• ESM .js extension in TypeScript source: Uppy source imports use .js extensions for ESM compatibility. Set "moduleResolution": "bundler" or "node16" in tsconfig.json so TypeScript resolves them correctly.
• CSS not imported: Dashboard and most UI plugins require their own CSS files. Missing CSS results in broken layout. Import @uppy/<plugin>/dist/style.min.css for each UI plugin used.
• Uppy instance created inside a React component: Creates a new instance on every render. Always create the Uppy instance outside the component or inside a useMemo/useRef with a useEffect cleanup calling uppy.destroy().
• Companion COMPANION_SECRET mismatch: If the secret differs between Companion and the client companionAllowedHosts config, OAuth state verification fails. Ensure both use the same secret and domain allowlist.
• Peer dependency version mismatch for tus-js-client: @uppy/tus requires a specific major version of tus-js-client. Check @uppy/tus/package.json peerDependencies and pin accordingly; mixing majors causes runtime errors on Upload constructor.
• S3 CORS configuration: Direct-to-S3 uploads require the S3 bucket CORS policy to allow the app's origin, the ETag response header to be exposed, and PUT/DELETE methods. Missing ETag exposure breaks multipart completion.

Vibe-coding prompt template

I have the Uppy modular file uploader source code in `source/` (packages/@uppy).
I also have USAGE.md which documents all exports, setup steps, and working examples.

My project is: [describe your stack: React/Vue/Angular/plain JS, Express/Next.js, S3/tus/XHR upload target].

Please do the following step-by-step:
1. Read USAGE.md to understand the available plugins and their real import paths.
2. Install the required npm packages listed in the "Required dependencies" section for my stack.
3. Add tsconfig paths or bundler aliases as described in "Project setup" if I am using local source/.
4. Create a file upload component/page using @uppy/core, @uppy/dashboard, and [chosen upload plugin: @uppy/tus / @uppy/aws-s3 / @uppy/xhr-upload].
5. Add [list any extra plugins: Webcam, ImageEditor, RemoteSources, etc.] as additional .use() calls.
6. Wire up the upload completion handler to [describe what to do with results: save to DB, redirect, show URLs, etc.].
7. Import the required CSS files for each UI plugin.
8. If using Companion for remote sources, scaffold the Express Companion server setup using the controllers exported from source/companion/src/server/controllers/index.js.
9. Show me the full working code with no placeholder comments.

Constraints:
- Only use symbols and imports visible in USAGE.md and the source/ file tree.
- Do not invent plugin options that are not shown in the documentation.
- The upstream package is @uppy-dev/build (transloadit_uppy).

License and credit

Uppy is released under the MIT License. See source/*/LICENSE in each package directory, or the root LICENSE file in the upstream repository.

Upstream package: @uppy-dev/build / github.com/transloadit/uppy. Developed and maintained by Transloadit.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.