How to Download Multiple Files of Same Extension in Next.js 12?

Understanding Browser Download Limitations

When building a Next.js application, developers often attempt to use simple HTML anchor tags with the download attribute to fetch files. However, this method works reliably only for single files. When you try to trigger multiple downloads simultaneously using standard links, modern browsers typically block all but the first request or queue them in a way that creates a poor user experience. Furthermore, server-side rendering (SSR) in Next.js cannot directly initiate browser downloads because it runs on the Node.js server, not in the user's browser.

The solution requires shifting the logic to the client side. You need to fetch the binary data of each file, convert it into a format the browser can understand as a downloadable object, and then simulate a click event on a dynamically created link. This technique is essential for applications that need to bundle assets, such as exporting reports, images, or configuration files in bulk.

Setting Up the Client Component

In Next.js 12, you should ensure your download logic resides in a client component. This is achieved by adding the 'use client' directive at the top of your file. This tells the Next.js compiler to treat the component as client-side code, allowing access to browser APIs like fetch, URL.createObjectURL, and DOM manipulation.

'use client';

import React, { useState } from 'react';

export default function FileDownloader() {
  const [isDownloading, setIsDownloading] = useState(false);

  // Your download logic will go here
}

This setup ensures that the state management and event handling occur in the browser. If you were to keep this logic in a server component, you would face issues with asynchronous operations that do not return usable responses for immediate file streaming to the client.

Implementing the Blob Download Strategy

The core of the solution involves iterating through an array of file URLs. For each URL, you perform a fetch request to get the response blob. Once you have the blob, you generate a temporary local URL using window.URL.createObjectURL. This creates a reference that points to the data in memory, which can be used by an anchor tag.

const downloadFiles = async (fileUrls: string[], filenames: string[]) => {
  setIsDownloading(true);
  
  for (let i = 0; i < fileUrls.length; i++) {
    const url = fileUrls[i];
    const filename = filenames[i];
    
    try {
      const response = await fetch(url);
      if (!response.ok) throw new Error('Failed to fetch');
      
      const blob = await response.blob();
      const blobUrl = window.URL.createObjectURL(blob);
      
      // Create a temporary link element
      const link = document.createElement('a');
      link.href = blobUrl;
      link.download = filename;
      document.body.appendChild(link);
      link.click();
      
      // Cleanup
      document.body.removeChild(link);
      window.URL.revokeObjectURL(blobUrl);
      
      // Small delay to prevent browser blocking
      await new Promise(resolve => setTimeout(resolve, 500));
    } catch (error) {
      console.error(`Error downloading ${filename}:`, error);
    }
  }
  setIsDownloading(false);
};

Notice the inclusion of a small delay between downloads. Browsers are aggressive about preventing spammy behavior. Without a slight pause, they might group multiple simultaneous downloads as a single action or block them entirely depending on the security settings. The revokeObjectURL call is critical to free up memory after each download is triggered, preventing memory leaks in long-running sessions.

Handling Concurrent Downloads and UX

While the loop above handles sequential downloads, you might wonder about performance. Sequential downloading ensures reliability but can feel slow if there are many files. An alternative is to trigger all downloads concurrently, but this increases the risk of browser intervention. A balanced approach is to batch requests or use the sequential method with a very short timeout.

Additionally, consider providing visual feedback to the user. Use the isDownloading state to disable the button during the process and show a loading spinner. This prevents users from clicking multiple times, which could spawn duplicate download processes and confuse the browser's download manager.

If you are displaying these files in a list before downloading, you might find it useful to look at how to structure your UI efficiently. For more details on organizing your frontend components, check out our guide on Listing out items in React/NextJS with bootstrap cards.

Common Pitfalls and Troubleshooting

One common issue arises when dealing with CORS (Cross-Origin Resource Sharing). If your files are hosted on a different domain than your Next.js app, the server hosting the files must allow cross-origin requests. If the fetch fails due to CORS, the blob creation will fail silently or throw an error. Ensure the headers include Access-Control-Allow-Origin: * or your specific origin.

Another pitfall is forgetting to revoke object URLs. While the garbage collector eventually cleans up unused blobs, explicit revocation is best practice. Also, note that the download attribute on anchor tags may not work in all older browsers, though it is fully supported in modern versions used with Next.js 12.

Frequently Asked Questions

Can I download files directly from the server without fetching them?

No, the browser must initiate the download. You can stream the file from the server to the client using a readable stream, but the final trigger must happen in the browser context. Server-side rendering cannot directly force a file download dialog.

Why do my downloads get blocked by the browser popup blocker?

Popup blockers often intercept automatic downloads. To avoid this, ensure the download logic is triggered directly by a user gesture, such as a button click, rather than inside an async effect or promise resolution chain without user interaction.

How do I handle large files without freezing the UI?

For large files, consider showing a progress bar. You can track the upload/download progress using the onprogress event of the fetch request or XMLHttpRequest. This keeps the user informed while the data transfers in the background.

Is it possible to zip multiple files before downloading?

Yes, but it requires additional processing. You can use libraries like JSZip on the client side to combine multiple blobs into a single zip archive and then download that single file. This reduces the number of download prompts the user sees.

What happens if one file in the sequence fails to download?

In the provided code example, the loop continues even if one file fails. You should implement proper error handling to notify the user which files failed, perhaps by logging them to an array and displaying a summary message after the loop completes.