Design a File Uploader

A production file uploader is a small distributed system. It has to keep memory bounded on a phone, recover from a flaky LTE connection mid-transfer, give the user trustworthy progress feedback, and hand a verified blob to the storage layer without trusting the filename or Content-Type it was given. A naive form post or a single XMLHttpRequest only works for the easy cases — once files cross ~10 MB or networks get unreliable, the design has to switch to chunked, resumable, and (often) direct-to-storage transfers. This article walks through the constraints that force those choices, the protocols that solve them, and how Dropbox, Google Drive, S3, and Slack actually wire it together.

Mental model

Four coupled decisions drive every other choice in an uploader:

1. Transfer unit. Single request (one FormData body) or many chunks (Blob.slice + PATCH/PUT). Single is simpler and works for small files; chunked is the only path that bounds memory and enables resume.
2. Concurrency. Within a chunked transfer, parts can flow sequentially (one in flight at a time, simplest backpressure) or in a bounded pool of parallel PUTs (S3 multipart, R2 multipart, Uppy @uppy/aws-s3). Parallelism multiplies throughput on high-BDP links but also multiplies the failure surface and the request budget.
3. Resume protocol. None, in-session only (offset stored client-side), or cross-session (server-stored upload resource that survives reloads, network swaps, and app crashes). tus 1.0.x is the open spec; AWS S3, Google Drive, and Dropbox each ship proprietary equivalents.
4. Data plane. Bytes through the API server (simple, but the server now eats the bandwidth) or directly to object storage via presigned URL (Slack, S3, GCS, R2). The latter requires a two-phase handshake but bypasses the API for the actual transfer.

Four browser invariants constrain those decisions, all rooted in the W3C File API:

• Blob.slice() is O(1): it returns a new Blob that references the same underlying bytes with new start/end positions¹. Slicing a 10 GiB file does not copy 10 GiB.
• URL.createObjectURL() leaks until you call revokeObjectURL()². Long-running SPAs that re-create previews accumulate memory until reload.
• file.type is a hint, never evidence. It comes from the registered extension, not content sniffing³. Server-side validation must read magic bytes.
• Fetch has no upload-progress event. Even with Chrome 105’s streaming-request bodies (ReadableStream + duplex: 'half', HTTP/2 only), the bytes a stream has enqueued are not the bytes the network has acked; treating them as progress is misleading⁴. XMLHttpRequest’s upload.progress is still the only first-party signal that tracks actual bytes-on-the-wire.

These four facts dictate everything below: chunking exists because of (1) and (3), revoke discipline exists because of (2), and the entire design defaults back to XHR because of (4).

The constraint surface

Browser-side constraints

Transfer mechanism trade-offs

Two practical takeaways from this table:

1. Use XHR per chunk when you want both bounded memory (chunking) and a real progress signal. The chunked-upload code samples below all do this.
2. Use streaming fetch only when the source itself is a stream (e.g. piping from a MediaStreamTrack or a TransformStream), and report progress from the application layer (chunks acknowledged), not from the request body.

Scale factors

Choosing a strategy

Path 1: Single-request upload (XHR + FormData)

The entire file is sent in one HTTP request. FormData builds a multipart/form-data body whose boundary is auto-generated and matched against the Content-Type header by the XHR spec — that’s the main reason to prefer it over hand-rolling the body.

Show 3 hidden lines4  onProgress?: (loaded: number, total: number) => void5  onComplete?: (response: unknown) => void6  onError?: (error: Error) => void7}89function uploadFile({ file, url, onProgress, onComplete, onError }: UploadOptions): () => void {10  const xhr = new XMLHttpRequest()1112  xhr.upload.addEventListener("progress", (e) => {13    if (e.lengthComputable) {14      onProgress?.(e.loaded, e.total)15    }16  })1718  xhr.addEventListener("load", () => {19    if (xhr.status >= 200 && xhr.status < 300) {20      onComplete?.(JSON.parse(xhr.responseText))21    } else {22      onError?.(new Error(`Upload failed: ${xhr.status}`))23    }24  })2526  xhr.addEventListener("error", () => onError?.(new Error("Network error")))2728  const formData = new FormData()29  formData.append("file", file)Show 6 hidden lines

Use this when files are small, the network is friendly, and re-upload on failure is cheap. The moment any of those is false, switch to chunked.

Path 2: Chunked upload with same-session resume

Slice the file with Blob.slice(), send chunks sequentially via XHR, and have the server return the next expected offset. On failure, the client HEADs the upload URL, reads the offset, and resumes from there — but only within the lifetime of the page (hence “same session”).

Show 5 hidden lines6  onComplete?: () => void7  onError?: (error: Error) => void8}910async function chunkedUpload({11  file,12  uploadUrl,13  chunkSize = 5 * 1024 * 1024,14  onProgress,15  onComplete,16  onError,17}: ChunkedUploadOptions): Promise<void> {18  let offset = 01920  // Ask the server where it left off (resume support)21  try {22    const headResponse = await fetch(uploadUrl, { method: "HEAD" })23    const serverOffset = headResponse.headers.get("Upload-Offset")24    if (serverOffset) {25      offset = parseInt(serverOffset, 10)26    }27  } catch {28    // No existing upload, start from 029  }3031  while (offset < file.size) {32    const chunk = file.slice(offset, offset + chunkSize)3334    await new Promise<void>((resolve, reject) => {35      const xhr = new XMLHttpRequest()3637      xhr.upload.addEventListener("progress", (e) => {38        if (e.lengthComputable) {39          onProgress?.(offset + e.loaded, file.size)40        }41      })4243      xhr.addEventListener("load", () => {44        if (xhr.status >= 200 && xhr.status < 300) {45          resolve()46        } else {47          reject(new Error(`Chunk upload failed: ${xhr.status}`))48        }49      })5051      xhr.addEventListener("error", () => reject(new Error("Network error")))5253      xhr.open("PATCH", uploadUrl)54      xhr.setRequestHeader("Content-Type", "application/offset+octet-stream")55      xhr.setRequestHeader("Upload-Offset", String(offset))56      xhr.send(chunk)57    })5859    offset += chunk.size60  }6162  onComplete?.()63}

Sizing chunks

There is no universally right chunk size. The trade-off is per-chunk overhead (TCP/TLS handshake amortization, request bookkeeping) versus per-chunk recovery cost (a failed chunk re-sends that chunk’s bytes and nothing else). Production minimums are protocol-defined:

A practical default rubric for client-driven sizing:

Trade-offs

• ✅ Constant memory regardless of file size
• ✅ Resume from the last successful offset within the page session
• ✅ Per-chunk progress plus intra-chunk progress from XHR
• ❌ More HTTP requests; per-chunk handshake overhead
• ❌ Server must track upload state
• ❌ Reload, refresh, or app background loses the in-memory File reference unless you re-attach it from the file picker (or persisted a FileSystemHandle — see File System Access API)

Parallel parts (S3-style multipart)

Pure tus and naive PATCH loops upload chunks one at a time — easy to reason about, but a single chunk’s RTT becomes the throughput cap on long-fat networks. The S3 multipart family inverts this: parts are independent objects keyed by (UploadId, PartNumber), the server accepts them in any order, and the client is expected to dispatch several in parallel⁶. Uppy’s @uppy/aws-s3 defaults to multipart for files larger than ~100 MiB and pumps parts through a bounded pool⁷.

Practical guard-rails:

• Bound the pool. 3–6 concurrent parts saturates most home and mobile links without thrashing. More than that wastes battery, congests TCP slow-start, and risks 503s from the storage edge.
• Watch the protocol limits. S3 caps every multipart upload at 10,000 parts and 5 TiB; parts must be 5 MiB–5 GiB except the last⁸. R2 enforces the same envelope plus an extra rule that all parts must be exactly the same size except the last — uneven sizes get rejected at CompleteMultipartUpload⁹.
• Track (PartNumber, ETag) client-side. Don’t ListParts to reconstruct it; the canonical S3 advice is to keep your own map and feed it to CompleteMultipartUpload⁶.
• Apply backpressure to the file reader, not just the network. With a parallel pool, your Blob.slice rate is now driven by how fast the slowest worker drains. A naive “queue all parts upfront” design materializes too many chunks at once and blows the memory budget you went chunked to avoid.

Path 3: tus protocol (cross-session resumable)

The tus 1.0.x resumable upload protocol standardizes the chunked-upload contract: a POST creates an upload resource with a server-assigned URL, HEAD returns the current offset, PATCH appends bytes, and the upload URL persists across sessions until the server expires it. Because the URL is server-side state, an upload can survive page reloads, OS restarts, and network changes — provided the client persists the URL (typically in IndexedDB) along with enough metadata to re-attach the original File.

Show 8 hidden lines9}1011class TusUpload {12  private uploadUrl: string | null = null13  private offset = 014  private aborted = false1516  constructor(private options: TusUploadOptions) {}1718  async start(): Promise<void> {19    const { file, endpoint, metadata, chunkSize = 5 * 1024 * 1024 } = this.options2021    if (!this.uploadUrl) {22      const encodedMetadata = metadata23        ? Object.entries(metadata)24            .map(([k, v]) => `${k} ${btoa(v)}`)25            .join(",")26        : undefined2728      const createResponse = await fetch(endpoint, {29        method: "POST",30        headers: {31          "Tus-Resumable": "1.0.0",32          "Upload-Length": String(file.size),33          ...(encodedMetadata && { "Upload-Metadata": encodedMetadata }),34        },35      })3637      if (createResponse.status !== 201) {38        throw new Error(`Failed to create upload: ${createResponse.status}`)39      }4041      this.uploadUrl = createResponse.headers.get("Location")42      if (!this.uploadUrl) {43        throw new Error("Server did not return upload URL")44      }45    }4647    const headResponse = await fetch(this.uploadUrl, {48      method: "HEAD",49      headers: { "Tus-Resumable": "1.0.0" },50    })5152    const serverOffset = headResponse.headers.get("Upload-Offset")53    this.offset = serverOffset ? parseInt(serverOffset, 10) : 05455    while (this.offset < file.size && !this.aborted) {56      const chunk = file.slice(this.offset, this.offset + chunkSize)5758      const patchResponse = await fetch(this.uploadUrl, {59        method: "PATCH",60        headers: {61          "Tus-Resumable": "1.0.0",62          "Upload-Offset": String(this.offset),63          "Content-Type": "application/offset+octet-stream",64        },65        body: chunk,66      })6768      if (patchResponse.status !== 204) {69        throw new Error(`Chunk upload failed: ${patchResponse.status}`)70      }7172      const newOffset = patchResponse.headers.get("Upload-Offset")73      this.offset = newOffset ? parseInt(newOffset, 10) : this.offset + chunk.size7475      this.options.onProgress?.(this.offset, file.size)76    }7778    if (!this.aborted) {79      this.options.onComplete?.(this.uploadUrl)80    }81  }8283  abort(): void {84    this.aborted = true85  }8687  getUploadUrl(): string | null {88    return this.uploadUrl89  }Show 1 hidden line

Headers and status codes that matter

All of those status semantics come straight from the tus 1.0.x spec. Production adopters include Cloudflare Stream, Vimeo, Supabase Storage, and Transloadit.

State machine

The protocol is small, but the state the client has to track across the protocol is what makes implementations subtle. Pause, visibility-change, server expiry, and checksum failure are all real states with their own transitions:

For parallel-parts variants (S3 multipart, tus Concatenation extension), the loop in Uploading is a worker pool rather than a single PATCH; the rest of the machine is unchanged.

Trade-offs

• ✅ Open standard with multiple server implementations (tusd, Spring, Phoenix, Rails, etc.)
• ✅ Cross-session resume — the upload URL outlives the page
• ✅ Optional checksum extension catches in-flight corruption
• ✅ Concatenation extension lets the client upload independent partial uploads in parallel and stitch them server-side (closest tus equivalent to S3 multipart parallelism)
• ❌ Built around fetch semantics; no intra-chunk progress (use chunk-completion events instead)
• ❌ The server must implement the protocol (or you proxy to a tus server)
• ❌ More round-trips than a custom protocol that batches metadata into the chunk request

Decision matrix

Direct-to-storage uploads

Whether you choose single, chunked, or tus, an orthogonal question is: do bytes flow through your API server, or directly to object storage? Routing them through the API is simple but means your servers eat the bandwidth, the request timeout budget, and the OOM blast radius. Direct-to-storage flips that: the API issues a short-lived presigned URL (S3, GCS, Slack’s files.getUploadURLExternal) and the client PUTs bytes straight to the storage edge, then comes back to “complete” the upload.

The pattern shows up under different names: S3 presigned PUT for single-shot uploads, S3 presigned CreateMultipartUpload for chunked, GCS resumable session URI, and Slack’s two-step files.getUploadURLExternal → files.completeUploadExternal flow. They all share the same skeleton: authorize once, transfer once (or many times), then finalize.

File selection and validation

Pickers and drops

The standard input handles both single and multiple selection, plus directory selection via the non-standard but widely supported webkitdirectory:

1<input type="file" accept="image/*,.pdf" multiple />2<input type="file" webkitdirectory />

webkitdirectory is supported on Chrome, Firefox, Safari, and Edge desktop, but not on mobile browsers¹⁰. When it works, each File object carries a webkitRelativePath so you can reconstruct the directory tree.

For drag-and-drop, prefer DataTransferItem.webkitGetAsEntry() (or its standards-track successor getAsFileSystemHandle()) over dataTransfer.files, because only the entry-based API gives you directory contents instead of just the dropped folder name¹¹:

Show 3 hidden lines4    e.dataTransfer!.dropEffect = "copy"5    element.classList.add("drag-over")6  }78  const handleDragLeave = () => {9    element.classList.remove("drag-over")10  }1112  const handleDrop = (e: DragEvent) => {13    e.preventDefault()14    element.classList.remove("drag-over")1516    const files: File[] = []1718    if (e.dataTransfer?.items) {19      for (const item of e.dataTransfer.items) {20        if (item.kind === "file") {21          const file = item.getAsFile()22          if (file) files.push(file)23        }24      }25    } else if (e.dataTransfer?.files) {26      files.push(...Array.from(e.dataTransfer.files))27    }2829    onFiles(files)30  }3132  element.addEventListener("dragover", handleDragOver)33  element.addEventListener("dragleave", handleDragLeave)34  element.addEventListener("drop", handleDrop)3536  return () => {37    element.removeEventListener("dragover", handleDragOver)38    element.removeEventListener("dragleave", handleDragLeave)39    element.removeEventListener("drop", handleDrop)Show 2 hidden lines

Magic-byte validation

file.type derives from the OS-registered extension, not the actual content³. For any security-sensitive surface, sniff the file header instead. The WebP spec is a good example of why a single check isn’t enough: it’s a RIFF container whose WEBP four-CC sits at byte offset 8, so naïve “first 4 bytes” matchers will misfire.

Show 2 hidden lines3  "image/png": [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],4  "image/gif": [0x47, 0x49, 0x46, 0x38], // "GIF8" — covers GIF87a and GIF89a5  "image/webp": [0x52, 0x49, 0x46, 0x46], // "RIFF" — verify "WEBP" at offset 86  "application/pdf": [0x25, 0x50, 0x44, 0x46], // "%PDF"7}89async function detectFileType(file: File): Promise<string | null> {10  const slice = file.slice(0, 12)11  const buffer = await slice.arrayBuffer()12  const bytes = new Uint8Array(buffer)1314  for (const [mimeType, signature] of Object.entries(MAGIC_SIGNATURES)) {15    if (signature.every((byte, i) => bytes[i] === byte)) {16      if (mimeType === "image/webp") {17        const webpMarker = new TextDecoder().decode(bytes.slice(8, 12))18        if (webpMarker !== "WEBP") continue19      }20      return mimeType21    }22  }2324  return file.type || null25}

Treat client-side detection as a UX optimization — the authoritative check belongs on the server, with both magic-byte sniffing and a deeper validator (e.g., libmagic, Apache Tika) for high-risk types.

Image dimension validation

1async function validateImageDimensions(2  file: File,3  maxWidth: number,4  maxHeight: number,5): Promise<{ width: number; height: number }> {6  const url = URL.createObjectURL(file)78  try {9    const img = await new Promise<HTMLImageElement>((resolve, reject) => {10      const image = new Image()11      image.onload = () => resolve(image)12      image.onerror = () => reject(new Error("Failed to load image"))13      image.src = url14    })1516    if (img.width > maxWidth || img.height > maxHeight) {17      throw new Error(`Image ${img.width}x${img.height} exceeds max ${maxWidth}x${maxHeight}`)18    }1920    return { width: img.width, height: img.height }21  } finally {22    URL.revokeObjectURL(url)23  }24}

Security

The OWASP File Upload Cheat Sheet is the source of truth here. The threats that catch most teams off guard:

SVGs are documents that can run JavaScript. A <script> tag, an onload="…" attribute, or a <foreignObject> carrying HTML are all valid SVG and all execute in the rendering origin if the file is served as image/svg+xml from a same-origin path:

1<svg xmlns="http://www.w3.org/2000/svg">2  <script>fetch('/api/me').then(r=>r.json()).then(send)</script>3</svg>

OWASP’s recommended mitigations: serve user uploads from a separate, sandboxed origin (so any XSS doesn’t run with your app’s cookies), force Content-Disposition: attachment, sanitize SVG server-side with a known-good library (DOMPurify for SVG profiles, svg-sanitizer, etc.), or convert to a raster format on ingest.

Filename attacks. The cheat sheet’s hard recommendation is to ignore the user filename entirely: assign a server-generated UUID, store the original name as metadata only. If you must keep user names, OWASP requires an allowlist (alphanumerics, hyphen, single dot), explicit blocking of leading dots, double dots, and null bytes, and validation of the extension after decoding any URL/percent escapes.

Content-Type spoofing. The browser sets Content-Type from the file extension; a .jpg can be a PHP script with the right magic bytes. Validate the content, not the header.

Size and rate limits. Without per-request size caps, a single large multipart body can exhaust server memory. Without per-IP/per-user rate limits, a presigned-URL endpoint can be abused to issue unbounded scratch storage. Enforce both.

Preview generation

URL.createObjectURL vs FileReader.readAsDataURL

createObjectURL is the right default for previews; the only meaningful gotcha is the manual revoke.

1function createImagePreview(file: File, imgElement: HTMLImageElement): () => void {2  const url = URL.createObjectURL(file)3  imgElement.src = url45  return () => URL.revokeObjectURL(url)6}78const cleanup = createImagePreview(file, previewImg)9cleanup()

Thumbnails off the main thread

For large images, decode in a worker. createImageBitmap accepts a Blob and is available on WorkerGlobalScope; OffscreenCanvas lets the worker rasterize without touching the DOM.

Show 2 hidden lines3  const maxSize = 20045  const bitmap = await createImageBitmap(file)67  let { width, height } = bitmap8  if (width > height) {9    if (width > maxSize) {10      height = (height * maxSize) / width11      width = maxSize12    }13  } else {14    if (height > maxSize) {15      width = (width * maxSize) / height16      height = maxSize17    }18  }1920  const canvas = new OffscreenCanvas(width, height)21  const ctx = canvas.getContext("2d")!22  ctx.drawImage(bitmap, 0, 0, width, height)2324  const blob = await canvas.convertToBlob({ type: "image/jpeg", quality: 0.8 })2526  self.postMessage(blob)27})

1const worker = new Worker("thumbnail-worker.ts", { type: "module" })23function generateThumbnail(file: File): Promise<Blob> {4  return new Promise((resolve) => {5    worker.onmessage = (e) => resolve(e.data)6    worker.postMessage(file)7  })8}

A 20 MP JPEG decode on a mid-tier mobile CPU is on the order of 100–200 ms — easily enough to drop frames if it lands on the main thread. The worker version takes the same wall time but the main thread keeps animating.

Non-image previews

Map MIME prefixes to icons; fall back to a generic file glyph:

1const FILE_ICONS: Record<string, string> = {2  "application/pdf": "pdf-icon.svg",3  "application/zip": "archive-icon.svg",4  "application/x-zip-compressed": "archive-icon.svg",5  "text/plain": "text-icon.svg",6  "video/": "video-icon.svg",7  "audio/": "audio-icon.svg",8}910function getFileIcon(file: File): string {11  if (FILE_ICONS[file.type]) {12    return FILE_ICONS[file.type]13  }1415  for (const [prefix, icon] of Object.entries(FILE_ICONS)) {16    if (prefix.endsWith("/") && file.type.startsWith(prefix)) {17      return icon18    }19  }2021  return "generic-file-icon.svg"22}

Progress, queueing, and retries

Smoothed progress with ETA

A single instantaneous speed sample is jumpy because chunked transfers naturally pulse. Use a rolling window — five seconds is a good default — to compute a smoothed bytes-per-second and turn that into a remaining-time estimate.

Show 5 hidden lines6  speed: number7  remaining: number8}910class ProgressTracker {11  private startTime = Date.now()12  private samples: Array<{ time: number; loaded: number }> = []1314  constructor(private total: number) {}1516  update(loaded: number): UploadProgress {17    const now = Date.now()18    this.samples.push({ time: now, loaded })1920    const cutoff = now - 500021    this.samples = this.samples.filter((s) => s.time > cutoff)2223    let speed = 024    if (this.samples.length >= 2) {25      const oldest = this.samples[0]26      const elapsed = (now - oldest.time) / 100027      const bytesTransferred = loaded - oldest.loaded28      speed = elapsed > 0 ? bytesTransferred / elapsed : 029    }3031    const remaining = speed > 0 ? (this.total - loaded) / speed : Infinity3233    return {34      loaded,35      total: this.total,36      percent: (loaded / this.total) * 100,37      speed,38      remaining,39    }40  }41}

Multi-file queue with bounded concurrency

A single-file uploader is a special case of a queue with concurrency 1. Production uploaders usually settle around three concurrent transfers — enough to overlap latency, not enough to thrash the network — and surface per-item state for the UI.

Show 8 hidden lines9}1011class UploadQueue {12  private queue: QueuedUpload[] = []13  private concurrency: number14  private activeCount = 015  private onUpdate?: (queue: QueuedUpload[]) => void1617  constructor(options: { concurrency?: number; onUpdate?: (queue: QueuedUpload[]) => void }) {18    this.concurrency = options.concurrency ?? 319    this.onUpdate = options.onUpdate20  }2122  add(files: File[]): void {23    const newItems = files.map((file) => ({24      id: crypto.randomUUID(),25      file,26      status: "pending" as UploadStatus,27      progress: 0,28    }))2930    this.queue.push(...newItems)31    this.notify()32    this.processNext()33  }3435  private async processNext(): Promise<void> {36    if (this.activeCount >= this.concurrency) return3738    const next = this.queue.find((item) => item.status === "pending")39    if (!next) return4041    this.activeCount++42    next.status = "uploading"43    this.notify()4445    try {46      await this.uploadFile(next)47      next.status = "completed"48      next.progress = 10049    } catch (error) {50      next.status = "failed"51      next.error = error as Error52    }5354    this.activeCount--55    this.notify()56    this.processNext()57  }5859  private async uploadFile(item: QueuedUpload): Promise<void> {60    // Implementation calls the real upload function and updates item.progress61  }6263  private notify(): void {64    this.onUpdate?.(this.queue)65  }6667  cancel(id: string): void {68    const item = this.queue.find((q) => q.id === id)69    if (item && item.status === "pending") {Show 16 hidden lines

Retry with exponential backoff and jittering

Network and 5xx errors are transient; 4xx errors are not. The retry policy has to know the difference, and it has to add jitter so a herd of clients doesn’t synchronize on the next attempt. For tus, a 409 is not a transient error in the usual sense — it means your offset is wrong, so the recovery is a HEAD to re-sync, not a fixed-delay retry of the same PATCH.

Show 3 hidden lines4): Promise<T> {5  const { maxRetries = 3, baseDelay = 1000 } = options6  let lastError: Error78  for (let attempt = 0; attempt <= maxRetries; attempt++) {9    try {10      return await uploadFn()11    } catch (error) {12      lastError = error as Error1314      if (error instanceof Response && error.status >= 400 && error.status < 500) {15        throw error16      }1718      if (attempt < maxRetries) {19        const delay = baseDelay * Math.pow(2, attempt)20        const jitter = delay * 0.2 * Math.random()21        await new Promise((r) => setTimeout(r, delay + jitter))22      }23    }24  }2526  throw lastError!27}

Surviving navigation: Service Workers and Background Fetch

Everything above assumes the page that started the upload is still alive when the upload finishes. On mobile that assumption breaks every time the user switches tabs, takes a call, or accidentally swipes the app away. Two browser primitives narrow that gap.

Service Worker as a proxy

Routing the chunk PATCH/PUT through a registered service worker via event.respondWith(fetch(event.request)) lets the SW cache part state, queue retries from sync events (Background Sync), and re-attempt a part the moment connectivity returns. The page can disappear, but only between events — once the SW itself is terminated, in-flight fetch calls are abandoned.

Background Fetch

Background Fetch is the only browser API that lets a transfer survive the page being closed entirely. The page hands a list of Request objects (with bodies) to registration.backgroundFetch.fetch(id, requests, options); the browser owns the transfer from that point, exposes OS-level progress UI, pauses across network changes, and wakes the service worker with backgroundfetchsuccess (or …fail / …abort) when it’s done¹².

File System Access API and persistent handles

The “you have to re-attach the file from the picker on next visit” problem has one major loophole on Chromium: a FileSystemHandle returned by showOpenFilePicker() is cloneable — you can store it in IndexedDB and getFile() against it on a later visit to recover a live File reference, subject to permission re-prompt¹⁴. That turns “user has to find the file again” into a one-tap permission grant on supported browsers.

1const [handle] = await window.showOpenFilePicker({ multiple: false })2await idbPut("uploads", { id: uploadId, handle })34const stored = await idbGet<{ handle: FileSystemFileHandle }>("uploads", uploadId)5if ((await stored.handle.queryPermission({ mode: "read" })) !== "granted") {6  if ((await stored.handle.requestPermission({ mode: "read" })) !== "granted") return7}8const file = await stored.handle.getFile()

Browser support: Chrome / Edge / Opera fully implement it; Safari ships only the Origin Private File System (OPFS) subset; Firefox does the same and rejects the picker methods entirely¹⁵. For Safari and Firefox, fall back to the file picker on next visit.

Cross-session resume state

For uploads that need to survive page reloads or device restarts, persist the upload metadata in IndexedDB. A plain File object isn’t persistable across reloads on its own (the user has to re-attach it via the file picker or a drag-and-drop), but the upload URL, offset, content hash, and (where supported) the FileSystemHandle are.

Show 5 hidden lines6  offset: number7  createdAt: number8  file?: File // Only present in same session9}1011class UploadStateStore {12  private db: IDBDatabase | null = null1314  async init(): Promise<void> {15    return new Promise((resolve, reject) => {16      const request = indexedDB.open("upload-state", 1)1718      request.onupgradeneeded = (e) => {19        const db = (e.target as IDBOpenDBRequest).result20        db.createObjectStore("uploads", { keyPath: "id" })21      }2223      request.onsuccess = (e) => {24        this.db = (e.target as IDBOpenDBRequest).result25        resolve()26      }2728      request.onerror = () => reject(request.error)29    })30  }3132  async save(state: StoredUploadState): Promise<void> {33    if (!this.db) throw new Error("DB not initialized")3435    return new Promise((resolve, reject) => {36      const tx = this.db!.transaction("uploads", "readwrite")37      const store = tx.objectStore("uploads")38      const request = store.put(state)39      request.onsuccess = () => resolve()40      request.onerror = () => reject(request.error)41    })42  }4344  async getAll(): Promise<StoredUploadState[]> {45    if (!this.db) throw new Error("DB not initialized")4647    return new Promise((resolve, reject) => {48      const tx = this.db!.transaction("uploads", "readonly")49      const store = tx.objectStore("uploads")Show 18 hidden lines

Storage quotas in 2026

Browsers cap per-origin storage as a fraction of the device disk. The numbers below come from the MDN Storage quotas reference; they’re the de-facto floor you should design around.

Memory hygiene

1// Loads the entire file into memory — fails on large mobile uploads.2const data = await file.arrayBuffer()3upload(data)

1// Constant memory regardless of file size.2for (let offset = 0; offset < file.size; offset += chunkSize) {3  const chunk = file.slice(offset, offset + chunkSize)4  await uploadChunk(chunk)5}

A simple wrapper makes blob-URL revocation impossible to forget on a per-component basis:

1const activeUrls = new Set<string>()23function createTrackedUrl(blob: Blob): string {4  const url = URL.createObjectURL(blob)5  activeUrls.add(url)6  return url7}89function revokeUrl(url: string): void {10  URL.revokeObjectURL(url)11  activeUrls.delete(url)12}1314function revokeAll(): void {15  activeUrls.forEach((url) => URL.revokeObjectURL(url))16  activeUrls.clear()17}

Workers, streams, hashing, and encryption

The browser’s main thread is shared with rendering and input handling; anything CPU-bound on a large file should not run on it. The toolbox:

• Worker / OffscreenCanvas — already shown for thumbnail decode. The same pattern carries hashing, compression, and encryption.
• Streams API — ReadableStream from Blob.stream(), TransformStream for incremental work, WritableStream to push to the network. Streams compose in a worker the same way they do on the main thread.
• CompressionStream / DecompressionStream — gzip / deflate / deflate-raw on a stream without pulling the whole blob into memory. Useful for log uploads or large textual payloads where the bandwidth saving is worth the CPU.
• SubtleCrypto — AES-GCM encrypt/decrypt is streaming-friendly per chunk because GCM is a counter-mode cipher; SHA-256 hashing is not, because digest() is one-shot⁵. For file-level SHA-256 you need a streaming WASM hasher (hash-wasm, noble-hashes, or a custom WASM module). Per-chunk SHA-256 (Merkle-style) is fine for chunk integrity but is not the same digest as the whole file.

A typical pipeline for client-side encryption + chunked upload composes those primitives:

1const key = await crypto.subtle.importKey(2  "raw",3  rawKeyBytes,4  { name: "AES-GCM" },5  false,6  ["encrypt"],7)89async function encryptChunk(plain: Uint8Array, partNumber: number): Promise<Uint8Array> {10  const iv = new Uint8Array(12)11  new DataView(iv.buffer).setUint32(8, partNumber, false)12  const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, plain)13  return new Uint8Array(ct)14}1516for (let part = 0, offset = 0; offset < file.size; part++, offset += CHUNK) {17  const slice = file.slice(offset, offset + CHUNK)18  const plain = new Uint8Array(await slice.arrayBuffer())19  const cipher = await encryptChunk(plain, part)20  await uploadPart(part, cipher)21}

Server-side post-processing

The server’s job doesn’t end at “bytes received”. Three pieces of work belong on the server, not the client, and none of them should block the upload-complete response:

• Authoritative content validation. Re-run magic-byte sniffing with a real library (libmagic, Apache Tika), enforce a per-tenant size cap, and reject anything the client claimed but didn’t deliver. The client’s check is a UX optimization — the server’s is policy.
• Antivirus / malware scanning. ClamAV is the OSS baseline; AWS S3 has ready-made GuardDuty Malware Protection for S3 and a Lambda-on-s3:ObjectCreated pattern. SVGs need an additional sanitization pass (DOMPurify SVG profile, svg-sanitizer, or rasterization on ingest); they will pass an AV scan and still execute script in the browser.
• Metadata extraction and derivative generation. EXIF strip for privacy, ffprobe for video duration / codec, ImageMagick / libvips for thumbnails and AVIF/WebP variants. Run these in a workflow (Step Functions, Temporal, Argo) keyed off the s3:ObjectCreated event so the upload-complete response stays cheap and the user doesn’t wait on a 30-second video transcode.

How real systems do it

Dropbox: content-defined blocks in Magic Pocket

Dropbox splits every file into immutable content-addressed blocks of up to 4 MiB and stores them in Magic Pocket, its in-house exabyte-scale blob store. Each block is identified by its hash, so two users uploading the same content store one copy. Blocks are aggregated into ~1 GiB buckets before erasure coding for storage efficiency¹⁶. The client side rsyncs against block hashes before upload, so editing a paragraph in a 100 MiB document only ships the changed blocks.

Google Drive: session-URI resumable

Drive’s resumable upload flow is a presigned chunked upload with explicit byte-range semantics. Initiate with a POST to get a Location URI, which is valid for one week. Upload chunks as PUT requests with Content-Range: bytes <start>-<end>/<total>. A 308 Resume Incomplete response carries a Range header advertising the bytes the server has actually persisted; the client resumes from the byte after Range’s end. Chunks must be a multiple of 256 KiB (except the final one).

S3 multipart upload

S3 multipart is a three-call protocol: CreateMultipartUpload returns an upload ID, UploadPart uploads each part and returns an ETag, CompleteMultipartUpload lists the parts in order. Limits worth memorizing: 5 MiB minimum per part (except the last), 10,000 parts maximum, 5 TiB maximum object size, 5 GiB maximum part. An abandoned upload sits as billable storage until you set a lifecycle rule to abort incomplete multipart uploads, which is usually mistake #1 in production.

Slack: presigned + completion handshake

Slack deprecated the legacy files.upload in favour of a two-phase API: files.getUploadURLExternal returns a short-lived upload_url and a file_id; the client POSTs the bytes directly to that URL; files.completeUploadExternal finalizes the file and shares it into the requested channel. The shape — sign, transfer direct, complete — is the same one S3, GCS, and Cloudflare Stream all expose.

Accessibility

A drop zone is just a button if you’re a keyboard user. Wire Enter/Space to the underlying <input type="file">, give the visible affordance a meaningful aria-label, and announce upload state via a polite live region:

1function AccessibleDropzone({ onFiles }: { onFiles: (files: File[]) => void }) {2  const inputRef = useRef<HTMLInputElement>(null);34  const handleKeyDown = (e: KeyboardEvent) => {5    if (e.key === 'Enter' || e.key === ' ') {6      e.preventDefault();7      inputRef.current?.click();8    }9  };1011  return (12    <div13      role="button"14      tabIndex={0}15      onKeyDown={handleKeyDown}16      aria-label="Upload files. Press Enter or Space to open file picker, or drag and drop files here."17    >18      <input19        ref={inputRef}20        type="file"21        multiple22        className="visually-hidden"23        onChange={(e) => onFiles(Array.from(e.target.files || []))}24      />25      <span aria-hidden="true">Drag files here or click to upload</span>26    </div>27  );28}

1function useProgressAnnouncement() {2  const [announcement, setAnnouncement] = useState('');34  const announce = useCallback((progress: number, fileName: string) => {5    if (progress === 0) {6      setAnnouncement(`Starting upload of ${fileName}`);7    } else if (progress === 100) {8      setAnnouncement(`${fileName} upload complete`);9    } else if (progress % 25 === 0) {10      setAnnouncement(`${fileName}: ${progress}% uploaded`);11    }12  }, []);1314  return {15    announce,16    AriaLive: () => (17      <div aria-live="polite" aria-atomic="true" className="visually-hidden">18        {announcement}19      </div>20    )21  };22}

Errors get an aria-live="assertive" region with a focusable retry control:

1function UploadError({ error, onRetry }: { error: Error; onRetry: () => void }) {2  return (3    <div role="alert" aria-live="assertive">4      <span>Upload failed: {error.message}</span>5      <button onClick={onRetry} aria-label="Retry failed upload">6        Retry7      </button>8    </div>9  );10}

Practical takeaways

• Pick the smallest mechanism that fits the file-size distribution and network reliability profile. Single XHR + FormData for small files on stable networks; chunked + XHR-per-chunk for large or mobile; tus or a custom resumable protocol for cross-session resume.
• Default to direct-to-storage with presigned URLs the moment your API would otherwise eat the bandwidth. The two-phase handshake is cheap; the bytes-through-API tax is not.
• For S3 / R2 multipart, parallelise parts through a bounded pool (3–6) and apply backpressure to the file reader as well as the network — otherwise you reintroduce the memory bound you went chunked to avoid. Remember the R2 equal-part-size quirk.
• XMLHttpRequest is the only API that gives you trustworthy upload progress in 2026. Streaming fetch exists for streaming sources, not for progress.
• Validate file types by content, not by header or extension, on both client and server. SVGs are documents and need explicit sanitization. The authoritative AV/scan/transcode pipeline lives on the server, off the user’s critical path.
• Decode preview thumbnails in a worker; never on the main thread for anything larger than a chat avatar. Hash and encrypt off the main thread too — and remember SubtleCrypto.digest is one-shot.
• Persist upload state (URL, offset, hash) in IndexedDB; on Chromium, persist the FileSystemHandle too so the user doesn’t re-pick on resume. Call navigator.storage.persist() for anything whose loss would force a restart.
• Use Service Worker proxying / Background Sync for retry resilience, and Background Fetch (where supported) when the upload must outlive the page.
• Always set an S3 lifecycle rule that aborts incomplete multipart uploads. Always.

Appendix

Prerequisites

• The browser File API (File, Blob, FileReader)
• XMLHttpRequest and fetch semantics
• HTTP multipart/form-data encoding

Terminology

References

• W3C File API Specification — authoritative File, Blob, FileReader, and URL.createObjectURL semantics
• WHATWG XMLHttpRequest Standard — FormData, upload progress events
• WHATWG HTML — Drag and Drop — drag-data-store modes, dataTransfer
• tus 1.0.x Resumable Upload Protocol — open standard for resumable uploads
• MDN: File API — implementation guide and browser support
• MDN: HTMLInputElement.webkitdirectory — directory selection support
• MDN: DataTransferItem.webkitGetAsEntry — directory drops
• MDN: Storage quotas and eviction criteria — per-browser quota math
• MDN: OffscreenCanvas — off-thread canvas
• Chrome for Developers: Streaming requests with the fetch API — Chrome 105 streaming uploads
• Jake Archibald: Fetch streams aren’t for progress — why streaming fetch progress is unreliable
• OWASP File Upload Cheat Sheet — security baseline
• AWS S3 Multipart Upload Overview — parallel parts, ETag tracking, completion contract
• AWS S3 Multipart Upload Limits — protocol minimums and maximums
• Cloudflare R2: Upload objects — R2 multipart uniform-part-size requirement
• Google Drive Upload API — resumable upload semantics
• Slack files.getUploadURLExternal — two-phase upload reference
• Uppy @uppy/aws-s3 — production multipart client with companion server
• Background Fetch API (MDN) and WICG draft — survival across navigation
• WHATWG File System Standard — FileSystemHandle, OPFS, writable streams
• SubtleCrypto.digest (MDN) — one-shot digest API and its consequences
• Streams Living Standard (WHATWG) — ReadableStream, TransformStream, WritableStream
• Dropbox: Inside the Magic Pocket — block-storage architecture