Complete Guide to File Upload with JavaScript Fetch API

Fundamentals of File Upload

In modern web development, file upload is a common functional requirement. JavaScript's Fetch API provides a clean and powerful way to implement this functionality. Compared to traditional XMLHttpRequest, Fetch API offers clearer syntax and better Promise support.

Using FormData Object

The FormData object is a key tool for handling form data, particularly useful for file upload scenarios. Through FormData, we can easily construct request bodies containing file data.

// Get file input element
const input = document.getElementById('fileinput');

// Create FormData instance
const formData = new FormData();
formData.append('file', input.files[0]);
formData.append('user', 'hubot');

In the above code, the append() method is used to add key-value pairs to the FormData object. The first parameter is the field name, and the second parameter is the field value, which can be a string, Blob, or File object.

Fetch Request Configuration

When using Fetch API for file upload requests, special attention should be paid to request configuration. Here's a complete implementation example:

const upload = (file) => {
  fetch('https://api.example.com/upload', {
    method: 'POST',
    headers: {
      // Note: When using FormData, usually no need to set Content-Type
      // Browser will automatically set appropriate Content-Type and boundary
    },
    body: formData
  })
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Upload successful:', data);
    // Handle success response
  })
  .catch(error => {
    console.error('Upload failed:', error);
    // Handle error cases
  });
};

Content-Type Header Handling

An important technical detail is the handling of Content-Type header. When using FormData as the request body, the browser automatically sets the appropriate Content-Type header, typically multipart/form-data with corresponding boundary.

// Browser automatically generates Content-Type like this:
// Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryfgtsKTYLsT7PNUVD

If you manually set the Content-Type header, it may break the proper encoding of FormData, causing the server to fail in correctly parsing the uploaded file.

Event Handling and File Selection

To respond to user file selection operations, you need to add event listeners to the file input element:

// Event handler function
const onSelectFile = () => {
  const file = input.files[0];
  if (file) {
    upload(file);
  }
};

// Add change event listener
input.addEventListener('change', onSelectFile, false);

Multiple File Upload Implementation

For scenarios requiring multiple file uploads, you can use loops and Promise.all to achieve parallel uploads:

const uploadMultipleFiles = async (files) => {
  const uploadPromises = [];
  
  for (let i = 0; i < files.length; i++) {
    const formData = new FormData();
    formData.append('file', files[i]);
    
    uploadPromises.push(
      fetch('https://api.example.com/upload', {
        method: 'POST',
        body: formData
      })
    );
  }
  
  try {
    const responses = await Promise.all(uploadPromises);
    const results = await Promise.all(
      responses.map(response => response.json())
    );
    console.log('All files uploaded:', results);
  } catch (error) {
    console.error('Error during file upload:', error);
  }
};

// Usage example
const handleMultipleFiles = () => {
  const files = input.files;
  if (files.length > 0) {
    uploadMultipleFiles(Array.from(files));
  }
};

Error Handling and User Experience

Robust error handling mechanisms are crucial for file upload functionality:

const uploadWithProgress = (file) => {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    
    // Listen to upload progress
    xhr.upload.addEventListener('progress', (event) => {
      if (event.lengthComputable) {
        const percentComplete = (event.loaded / event.total) * 100;
        console.log(`Upload progress: ${percentComplete.toFixed(2)}%`);
      }
    });
    
    xhr.addEventListener('load', () => {
      if (xhr.status === 200) {
        resolve(JSON.parse(xhr.responseText));
      } else {
        reject(new Error(`Upload failed: ${xhr.status}`));
      }
    });
    
    xhr.addEventListener('error', () => {
      reject(new Error('Network error'));
    });
    
    const formData = new FormData();
    formData.append('file', file);
    
    xhr.open('POST', 'https://api.example.com/upload');
    xhr.send(formData);
  });
};

// Combined with Fetch API usage
const enhancedUpload = async (file) => {
  try {
    // Here you can use XMLHttpRequest to get upload progress
    const result = await uploadWithProgress(file);
    console.log('File upload successful:', result);
  } catch (error) {
    console.error('File upload failed:', error.message);
    // Provide user-friendly error messages
    alert(`Upload failed: ${error.message}`);
  }
};

Best Practices and Considerations

In actual development, the following best practices should be considered:

1. File Type Validation: Validate file type and size before upload
2. Security Considerations: Implement CSRF protection and other security measures
3. Performance Optimization: Consider chunked upload for large files
4. User Experience: Provide upload progress indicators and cancel functionality

// File validation example
const validateFile = (file) => {
  const maxSize = 10 * 1024 * 1024; // 10MB
  const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
  
  if (file.size > maxSize) {
    throw new Error('File size cannot exceed 10MB');
  }
  
  if (!allowedTypes.includes(file.type)) {
    throw new Error('Unsupported file type');
  }
  
  return true;
};

// Enhanced upload function
const safeUpload = async (file) => {
  try {
    validateFile(file);
    
    const formData = new FormData();
    formData.append('file', file);
    
    const response = await fetch('https://api.example.com/upload', {
      method: 'POST',
      body: formData
    });
    
    if (!response.ok) {
      throw new Error(`Server error: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Error during upload process:', error);
    throw error;
  }
};

Through the complete implementation solutions above, developers can build fully functional file upload features with excellent user experience. These techniques are not only applicable to simple file upload scenarios but can also be extended to more complex business requirements.