# upup

upup is an MIT-licensed, self-hosted file uploader: one headless core plus
native, DOM-identical UI packages for React, Vue, Svelte, Angular, Vanilla JS,
and Preact, with optional server-mode uploads and cloud-drive sources.

## Docs

- [Use upup with AI assistants](https://useupup.com/docs/ai-assistants/): How coding agents (Claude Code, Cursor, and others) can discover and correctly integrate upup — including machine-readable context files and a paste-ready context block.
- [Azure SAS Responses](https://useupup.com/docs/api-reference/azure-generate-sas-url/): Return an Azure Blob SAS URL shaped as upup's presign contract so the browser can PUT directly to blob storage in client mode.
- [Error Codes](https://useupup.com/docs/api-reference/error-codes/): The complete UpupErrorCode enum, the seven UpupError classes that carry them, restriction reasons, and the response parser that turns server or S3 error bodies into typed errors.
- [Events](https://useupup.com/docs/api-reference/events/): The complete upup event catalog — all 52 typed core events with their payloads, plus the React callback props and the core event each one is driven by.
- [S3 Presign Responses](https://useupup.com/docs/api-reference/s3-generate-presigned-url/): The PresignedUrlResponse shape your client-mode presign endpoint returns so upup can upload bytes directly to S3.
- [Server HTTP API](https://useupup.com/docs/api-reference/server-http/): The complete HTTP contract of @upupjs/server — every route, request and response shape, status code, and operational header — for wiring a custom client or debugging a live handler.
- [Theme Slots](https://useupup.com/docs/api-reference/upupuploader/classnames/): The stable per-element styling API — theme.slots keyed by component then slot, plus theme.mode for the color scheme.
- [Event Handlers](https://useupup.com/docs/api-reference/upupuploader/event-handlers/): The UpupUploader callback props — onFilesSelected, onUploadStart, progress, per-file and batch completion, onFileRemoved, and onError — mirroring core upload state.
- [Icon Prop](https://useupup.com/docs/api-reference/upupuploader/icon-prop/): Override the UpupUploader's built-in icons — camera, delete, rotate, add-more, and loader — with any React component that accepts a className.
- [Image Editor](https://useupup.com/docs/api-reference/upupuploader/image-editor/): Enable in-uploader cropping, annotation, filters, and watermarking with the imageEditor prop — available in the React and Preact packages only.
- [Optional Props](https://useupup.com/docs/api-reference/upupuploader/optional-props/): The complete optional-prop reference for UpupUploader — behavior, file validation, the processing pipeline, upload reliability, sources, appearance, localization, plus the headless-only engine options.
- [Ref API](https://useupup.com/docs/api-reference/upupuploader/ref-api/): The UploaderRef imperative surface — a useUpload() accessor exposing files, progress, and the upload, uploadFiles, setFiles, and replaceFiles commands.
- [Required Props](https://useupup.com/docs/api-reference/upupuploader/required-props/): UpupUploader runs with no upload target as a local file collector; for real uploads, configure exactly one of uploadEndpoint, serverUrl, or resumable.endpoint.
- [Code Examples](https://useupup.com/docs/code-examples/): Ready-to-copy upup snippets — source pickers, client-mode uploads, a presign endpoint handler, and server-mode wiring.
- [upup vs FilePond](https://useupup.com/docs/comparisons/upup-vs-filepond/): An honest, factual comparison of upup and FilePond — a polished, accessible file uploader with first-party framework adapters — to help you choose.
- [upup vs react-dropzone](https://useupup.com/docs/comparisons/upup-vs-react-dropzone/): An honest, factual comparison of upup and react-dropzone — a headless drag-and-drop primitive versus a full file uploader — so you can pick the right scope.
- [upup vs UploadThing](https://useupup.com/docs/comparisons/upup-vs-uploadthing/): An honest, factual comparison of upup and UploadThing — a self-hosted MIT library versus a managed hosted upload service — so you can choose the right model.
- [upup vs Uppy](https://useupup.com/docs/comparisons/upup-vs-uppy/): An honest, factual comparison of upup and Uppy — two MIT-licensed file uploaders with headless cores, cloud drives, and resumable uploads — to help you choose.
- [Credentials and CORS](https://useupup.com/docs/credentials-configuration/): Keep storage keys and OAuth client secrets in server mode; configure your bucket's CORS policy for browser direct uploads.
- [Error Handling](https://useupup.com/docs/error-handling/): upup reports failures as a typed UpupError taxonomy with stable codes — narrow by instanceof or error code, and configure automatic or manual retries.
- [Getting Started](https://useupup.com/docs/getting-started/): Install upup and run your first upload — local file selection, client uploads straight to your storage, or full server mode with @upupjs/server.
- [Accessibility](https://useupup.com/docs/guides/accessibility/): What upup's uploader ships by default — keyboard interaction, ARIA roles and live regions, focus management on overlays, the animations prop and prefers-reduced-motion handling — and the parts that stay your responsibility.
- [Auth Recipes](https://useupup.com/docs/guides/auth-recipes/): Wire your existing auth into @upupjs/server — one getUserId hook, recipes for Better Auth, NextAuth, Clerk and raw JWT, plus Redis and SQL TokenStores.
- [Authenticate uploads with Better Auth](https://useupup.com/docs/guides/auth/better-auth/): Wire a Better Auth session into @upupjs/server so every upload is scoped to the signed-in user — the getUserId hook, gated sessions, uid binding.
- [Authenticate uploads with Clerk](https://useupup.com/docs/guides/auth/clerk/): Scope S3 uploads to the Clerk user — authenticateRequest inside @upupjs/server's getUserId hook, why authorizedParties is mandatory, and multipart uid binding.
- [Authenticate uploads with a custom JWT](https://useupup.com/docs/guides/auth/custom-jwt/): Verify your own JWT inside @upupjs/server's getUserId hook with jose — bearer or cookie, shared secrets, and remote JWKS for asymmetric tokens.
- [Authenticate uploads with NextAuth (Auth.js v5)](https://useupup.com/docs/guides/auth/next-auth/): Scope @upupjs/server uploads to the NextAuth session — the auth() helper in the App Router, getToken outside a request context, and the missing session.user.id.
- [Error Monitoring](https://useupup.com/docs/guides/error-monitoring/): Wire upup's structured errors — upload-error events, UpupError codes, and the server onError seam — into your error tracker.
- [File Processing](https://useupup.com/docs/guides/file-processing/): upup's client-side pipeline — image compression, HEIC to JPEG conversion, EXIF stripping, thumbnails, SHA-256 checksums and deduplication, Web Worker offload, and custom steps.
- [Headless Usage](https://useupup.com/docs/guides/headless/): Build your own uploader UI on top of upup's engine — the useUpupUpload React hook, driving UpupCore directly in any runtime, and the webWorker, HEIC, and resumable pipeline opt-ins.
- [Client Mode vs Server Mode](https://useupup.com/docs/guides/modes/): Choose between client mode (your presign endpoint) and server mode (@upupjs/server proxies uploads) — what runs where and when to pick each.
- [Plugins & Extensions](https://useupup.com/docs/guides/plugins/): Enable upup's built-in cloud-drive plugins with the cloudDrives config, compare client- and server-mode drives, and register third-party plugins on UpupCore.
- [Client-side image compression before upload](https://useupup.com/docs/guides/processing/compression/): Compress and resize images in the browser before they upload — quality, maxWidthOrHeight and maxSizeMB options, the size-target backoff, and output formats.
- [Custom file processing pipeline steps](https://useupup.com/docs/guides/processing/custom-steps/): Write your own upup PipelineStep — the contract, safe UploadFile cloning, registering a custom pipeline, and Web Worker offload with main-thread fallback.
- [Convert HEIC to JPEG in the browser](https://useupup.com/docs/guides/processing/heic-conversion/): Convert iPhone HEIC/HEIF photos to JPEG before upload with upup — install the optional libheif decoder, matching rules, and failure behavior.
- [Reliability](https://useupup.com/docs/guides/reliability/): How upup survives flaky networks — the per-file retry policy and its backoff math, custom success predicates, upload concurrency, online/offline events, and the difference between crash recovery and multipart session resume.
- [File upload server with Express and S3](https://useupup.com/docs/guides/server-adapters/express/): Mount @upupjs/server on an Express route with createUpupMiddleware — install, config, the express.json() ordering trap, proxy origins, and CORS.
- [File upload server with Fastify and S3](https://useupup.com/docs/guides/server-adapters/fastify/): Register @upupjs/server as a Fastify plugin with createUpupPlugin — install, the mount-path option, body parsing, trustProxy origins, and CORS.
- [File upload server with Hono and S3](https://useupup.com/docs/guides/server-adapters/hono/): Wire @upupjs/server into Hono with createUpupRoutes — the web-native mount, no body parsing, edge-runtime bindings, and CORS.
- [File upload server with Next.js and S3](https://useupup.com/docs/guides/server-adapters/nextjs/): Mount @upupjs/server in Next.js — App Router via createUpupNextHandler, Pages Router via createUpupPagesHandler, plus proxy origins, bodyParser, and CORS.
- [Server Auth & Trust Model](https://useupup.com/docs/guides/server-auth/): How @upupjs/server authenticates uploads — the mandatory HMAC upload-token secret, the secure-by-default 403 on anonymous uploads, per-user key scoping, and what forged requests get.
- [Server Mode — Setup](https://useupup.com/docs/guides/server-mode-setup/): Set up mode="server" — mount createUpupHandler, configure storage, secrets, limits and hooks, then pick an adapter — Express, Fastify, Hono, or Next.js.
- [Upload Sources](https://useupup.com/docs/guides/sources/): Every input the uploader ships — local files, drag-and-drop, paste, folder upload, camera, microphone, screen capture, URL import, and cloud drives — plus the sources prop that decides which chips appear.
- [Storage Providers](https://useupup.com/docs/guides/storage-providers/): Connect upup to any S3-compatible storage — AWS S3, Cloudflare R2, MinIO, Backblaze B2, DigitalOcean Spaces, Wasabi, and more — with the full provider list, the shared storage config shape, and a setup guide per provider.
- [Upload files to Amazon S3](https://useupup.com/docs/guides/storage/aws-s3/): Upload files to AWS S3 from React, Vue, Svelte, Angular, or plain JS with upup — bucket setup, IAM policy, CORS, and a copy-paste createUpupHandler config.
- [Upload files to Azure Blob Storage](https://useupup.com/docs/guides/storage/azure-blob/): Azure Blob Storage has no S3 API, so @upupjs/server rejects it. Upload to Azure from React, Vue, Svelte, or plain JS with upup via client mode and a SAS URL.
- [Upload files to Backblaze B2](https://useupup.com/docs/guides/storage/backblaze-b2/): Upload files to Backblaze B2 from React, Vue, Svelte, or plain JS with upup — application keys, the region-scoped S3 endpoint, CORS, and a copy-paste config.
- [Upload files to Cloudflare R2](https://useupup.com/docs/guides/storage/cloudflare-r2/): Upload files to Cloudflare R2 from React, Vue, Svelte, or plain JS with upup — account-scoped endpoint, region auto, API tokens, CORS, and a copy-paste config.
- [Upload files to DigitalOcean Spaces](https://useupup.com/docs/guides/storage/digitalocean-spaces/): Upload files to DigitalOcean Spaces from React, Vue, Svelte, or plain JS with upup — Spaces keys, the region endpoint, CORS, the CDN, and a copy-paste config.
- [Upload files to MinIO](https://useupup.com/docs/guides/storage/minio/): Upload files to a self-hosted MinIO server from React, Vue, Svelte, or plain JS with upup — Docker setup, path-style addressing, CORS, and a copy-paste config.
- [Upload files to any S3-compatible storage](https://useupup.com/docs/guides/storage/s3-compatible/): Upload files to Wasabi, Google Cloud Storage, Supabase, Hetzner, Scaleway, Storj, and any other S3-compatible store from React, Vue, or plain JS with upup.
- [Theming](https://useupup.com/docs/guides/theming/): Style the upup uploader with the theme prop — light/dark/system modes, design tokens exposed as CSS variables, per-component slot class overrides, and the stable data-upup-slot DOM hooks for raw CSS.
- [Write a custom upup plugin](https://useupup.com/docs/guides/writing-plugins/): Build a custom upload-source plugin for upup — the UpupPlugin contract, namespaced events, registering with core.use(), and subclassing PopupOAuthPlugin.
- [upup Documentation](https://useupup.com/docs/): A file uploader with a native UI for React, Vue, Svelte, Angular, Vanilla JS, and Preact, built on a shared headless core with an optional server mode.
- [Localization (i18n)](https://useupup.com/docs/localization/): upup ships nine ICU locale bundles from @upupjs/core/i18n — set the locale on any framework's uploader, override individual namespaced message keys, and get automatic RTL and pluralization.
- [Migrating from v1 to v3](https://useupup.com/docs/migration/v1-to-v3/): Upgrade from upup v1 (upup-react-file-uploader) to v3 — the package rename to @upupjs/react, the full v1→v3 prop map, the UpupError/UpupErrorCode taxonomy, and client- vs server-mode uploads.
- [Angular Quickstart](https://useupup.com/docs/quickstarts/angular/): Add a full-featured file uploader to an Angular 19+ app with @upupjs/angular — a standalone component port of the canonical React UI, with cloud drives, camera, and resumable uploads.
- [Next.js Quickstart](https://useupup.com/docs/quickstarts/next/): Add a full-featured file uploader to a Next.js app with @upupjs/next — the client UI and the server handlers in one install, split so the AWS SDK never reaches your client bundle.
- [Preact Quickstart](https://useupup.com/docs/quickstarts/preact/): Add a full-featured file uploader to a Preact app with @upupjs/preact — a preact/compat re-export of @upupjs/react, same UI and API, with cloud drives, camera, and resumable uploads.
- [React Quickstart](https://useupup.com/docs/quickstarts/react/): Add a full-featured file uploader to a React 19 app with @upupjs/react — drag-and-drop, cloud drives, camera, and resumable uploads, with no upload server to run.
- [Svelte Quickstart](https://useupup.com/docs/quickstarts/svelte/): Add a full-featured file uploader to a Svelte 5 app with @upupjs/svelte — a native port of the canonical React UI, DOM-identical, with cloud drives, camera, and resumable uploads.
- [Vanilla JS Quickstart](https://useupup.com/docs/quickstarts/vanilla/): Add a full-featured file uploader to any page with @upupjs/vanilla — framework-free, DOM-identical to the canonical React UI, with cloud drives, camera, and resumable uploads.
- [Vue Quickstart](https://useupup.com/docs/quickstarts/vue/): Add a full-featured file uploader to a Vue 3 app with @upupjs/vue — a native port of the canonical React UI, DOM-identical, with cloud drives, camera, and resumable uploads.
- [Resumable Uploads](https://useupup.com/docs/resumable-uploads/): Two resumable protocols — S3 multipart through @upupjs/server, or tus against an external tus-compatible service. Full option reference, part-size rules, and what each protocol actually resumes.