How to Handle Large File Uploads — Performance Guide

Handling large file uploads (100MB+) requires different techniques than standard form submissions. This guide covers chunked upload, resumable transfers, progress tracking, and testing strategies using sample files from 1MB to 10GB.

Why large uploads fail

Standard file uploads break at scale for several reasons: server timeout limits (typically 30-60 seconds), proxy body size limits (Nginx default: 1MB), browser memory constraints, and network interruptions. Each needs a specific solution.

Chunked upload implementation

async function uploadChunked(file, chunkSize = 5 * 1024 * 1024) {
  const totalChunks = Math.ceil(file.size / chunkSize);
  const uploadId = crypto.randomUUID();

  for (let i = 0; i < totalChunks; i++) {
    const start = i * chunkSize;
    const chunk = file.slice(start, start + chunkSize);

    await fetch('/api/upload', {
      method: 'POST',
      headers: {
        'X-Upload-Id': uploadId,
        'X-Chunk-Index': String(i),
        'X-Total-Chunks': String(totalChunks),
      },
      body: chunk,
    });
  }
}

Testing with sample files

Download test files at various sizes to validate your implementation:

• 1MB — basic functionality
• 100MB — standard stress test (most important)
• 500MB — timeout and resume testing
• 1GB — extreme edge case

Progress tracking

function uploadWithProgress(file, onProgress) {
  const xhr = new XMLHttpRequest();
  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) {
      onProgress(Math.round((e.loaded / e.total) * 100));
    }
  });
  xhr.open('POST', '/api/upload');
  xhr.send(file);
}

Server-side configuration

# Nginx — increase body size limit
client_max_body_size 500m;
proxy_read_timeout 300s;

# Node.js Express
# app.use(express.json({ limit: '500mb' }));

Resumable uploads with tus protocol

For production applications handling files over 100MB, consider the tus protocol. Libraries like tus-js-client handle chunking, resume after failure, and progress tracking automatically. Test with our large test files to verify your tus server handles edge cases.

Testing checklist

• Upload completes for 100MB file
• Progress bar updates smoothly
• Resume works after network drop (disconnect Wi-Fi mid-upload)
• Server returns helpful error for files exceeding size limit
• Multiple simultaneous uploads don't interfere
• Cancel button works cleanly