Documentation menu

 

View as Markdown

Guides

Task-focused guides for running upup in production: picking a mode, mounting the server package on your framework, scoping uploads to your users, connecting a storage provider, processing files before they upload, and making the uploader look and behave the way your app needs. New to upup? Start with Getting Started and the quickstart for your framework.

Modes and server setup

  • Client Mode vs Server Mode — what runs where in each mode, and when to pick each.
  • Server Mode Setup — mount createUpupHandler, configure S3 storage, secrets, limits and hooks.
  • Express — mount @useupup/server on an Express route with createUpupMiddleware.
  • Fastify — register @useupup/server as a Fastify plugin with createUpupPlugin.
  • Hono — the web-native mount with createUpupRoutes, including edge runtimes.
  • Next.js — App Router and Pages Router handlers from @useupup/next.

Auth

  • Server Auth & Trust Model — the HMAC upload-token secret, the secure-by-default 403 on anonymous uploads, and per-user scoping.
  • Auth Recipes — one getUserId hook, plus Redis and SQL token stores.
  • Better Auth — scope every upload to the signed-in Better Auth session.
  • NextAuth (Auth.js v5) — the auth() helper in the App Router and getToken outside a request.
  • Clerk — authenticateRequest inside getUserId, and why authorizedParties is mandatory.
  • Custom JWT — verify your own bearer or cookie JWT with jose, including remote JWKS.

Storage

  • Storage Providers — how upup connects to S3-compatible storage, the full storage.type table, and why Azure Blob Storage is the exception.
  • Amazon S3 — bucket setup, the IAM policy, CORS, and a createUpupHandler config.
  • Cloudflare R2 — the account-scoped endpoint, region auto, API tokens, and CORS.
  • Backblaze B2 — application keys, the region-scoped S3 endpoint, and CORS.
  • DigitalOcean Spaces — Spaces access keys, the regional endpoint, CORS, and the CDN.
  • MinIO — a self-hosted MinIO server with Docker, path-style addressing, and CORS.
  • Azure Blob Storage — client mode only: a SAS URL from your endpoint and the mandatory x-ms-blob-type header.
  • Any S3-compatible storage — Wasabi, Google Cloud Storage, Supabase, Hetzner, Scaleway, Storj, and more.

Files and sources

  • File Processing — the client-side pipeline: compression, HEIC conversion, EXIF stripping, thumbnails, and checksums.
  • Image compression — compress and resize images in the browser before they upload.
  • HEIC to JPEG — convert iPhone HEIC/HEIF photos with the optional libheif decoder.
  • Custom pipeline steps — write your own PipelineStep, with Web Worker offload.
  • Upload Sources — local files, drag and drop, paste, folders, camera, microphone, screen capture, URL import, and cloud drives.
  • Reliability — per-file retries and backoff, upload concurrency, and multipart resume.
  • Error Monitoring — send upload-error events and UpupError codes to your error tracker.

UI and extensibility

  • Theming — light, dark and system modes, design tokens, and slot class overrides.
  • Accessibility — keyboard interaction, ARIA live regions, focus management, and reduced motion.
  • Headless Usage — build your own UI on the upup engine with useUpupUpload or UpupCore.
  • Plugins & Extensions — enable the built-in cloud-drive plugins and register third-party ones.
  • Write a custom plugin — the UpupPlugin contract, namespaced events, and PopupOAuthPlugin.