Electron File Download Manager

A simple and easy to use file download manager for Electron applications. Designed in response to the many issues around electron-dl and provides a more robust and reliable solution for downloading files in Electron.

Use cases:

• Download files from a URL
• Get an id associated with the download to track it
• Optionally show a "Save As" dialog
• Get progress updates on the download
• Be able to cancel / pause / resume downloads
• Support multiple downloads at once

Electron 26.0.0 or later is required.

1// In main process
2// Not a working example, just a demonstration of the API
3import { ElectronDownloadManager } from 'electron-dl-manager';
4
5const manager = new ElectronDownloadManager();
6
7// Start a download
8const id = await manager.download({
9  window: browserWindowInstance,
10  url: 'https://example.com/file.zip',
11  saveDialogOptions: {
12    title: 'Save File',
13  },
14  callbacks: {
15    onDownloadStarted: async ({ id, item, webContents }) => {
16      // Do something with the download id
17    },
18    onDownloadProgress: async (...) => {},
19    onDownloadCompleted: async (...) => {},
20    onDownloadCancelled: async (...) => {},
21    onDownloadInterrupted: async (...) => {},
22    onError: (err, data) => {},
23  }
24});
25
26manager.cancelDownload(id);
27manager.pauseDownload(id);
28manager.resumeDownload(id);

Table of contents

• Electron File Download Manager
• Installation
• Getting started
• API
  • Class: ElectronDownloadManager
    • constructor()
    • download()
      • Interface: DownloadParams
      • Interface: DownloadManagerCallbacks
    • cancelDownload()
    • pauseDownload()
    • resumeDownload()
    • getActiveDownloadCount()
    • getDownloadData()
  • Class: DownloadData
    • Properties
      • Formatting download progress
    • isDownloadInProgress()
    • isDownloadPaused()
    • isDownloadResumable()
    • isDownloadCancelled()
    • isDownloadInterrupted()
    • isDownloadCompleted()
• Mock class
• FAQ
• Acknowledgments

Installation

1$ npm install electron-dl-manager

Getting started

You'll want to use electron-dl-manager in the main process of your Electron application where you will be handling the file downloads.

In this example, we use IPC handlers / invokers to communicate between the main and renderer processes, but you can use any IPC strategy you want.

1// MainIpcHandlers.ts
2
3import { ElectronDownloadManager } from 'electron-dl-manager';
4import { ipcMain } from 'electron';
5
6const manager = new ElectronDownloadManager();
7
8// Renderer would invoke this handler to start a download
9ipcMain.handle('download-file', async (event, args) => {
10  const { url } = args;
11
12  let downloadId
13  const browserWindow = BrowserWindow.fromId(event.sender.id)
14
15  // You *must* call manager.download() with await or 
16  // you may get unexpected behavior
17  downloadId = await manager.download({
18    window: browserWindow,
19    url,
20    // If you want to download without a save as dialog
21    saveAsFilename: 'file.zip',
22    directory: '/directory/where/to/save',
23    // If you want to download with a save as dialog
24    saveDialogOptions: {
25      title: 'Save File',
26    },
27    callbacks: {
28      // item is an instance of Electron.DownloadItem
29      onDownloadStarted: async ({ id, item, resolvedFilename }) => {
30        // Send the download id back to the renderer along
31        // with some other data
32        browserWindow.webContents.invoke('download-started', {
33          id,
34          // The filename that the file will be saved as
35          filename: resolvedFilename,
36          // Get the file size to be downloaded in bytes
37          totalBytes: item.getTotalBytes(),
38        });
39      },
40      onDownloadProgress: async ({ id, item, percentCompleted }) => {
41        // Send the download progress back to the renderer
42        browserWindow.webContents.invoke('download-progress', {
43          id,
44          percentCompleted,
45          // Get the number of bytes received so far
46          bytesReceived: item.getReceivedBytes(),
47        });
48      },
49      onDownloadCompleted: async ({ id, item }) => {
50        // Send the download completion back to the renderer
51        browserWindow.webContents.invoke('download-completed', {
52          id,
53          // Get the path to the file that was downloaded
54          filePath: item.getSavePath(),
55        });
56      },
57      onError: (err, data) => {
58        // ... handle any errors
59      }
60    }
61  });
62
63  // Pause the download
64  manager.pauseDownload(downloadId);
65});

API

Class: ElectronDownloadManager

Manages file downloads in an Electron application.

constructor()

1constructor(params: DownloadManagerConstructorParams)

1interface DownloadManagerConstructorParams {
2  /**
3   * If defined, will log out internal debug messages. Useful for
4   * troubleshooting downloads. Does not log out progress due to
5   * how frequent it can be.
6   */
7  debugLogger?: (message: string) => void
8}

download()

Starts a file download. Returns the id of the download.

1download(params: DownloadParams): Promise<string>

Interface: DownloadParams

1interface DownloadParams {
2  /**
3   * The Electron.BrowserWindow instance
4   */
5  window: BrowserWindow
6  /**
7   * The URL to download
8   */
9  url: string
10  /**
11   * The callbacks to define to listen for download events
12   */
13  callbacks: DownloadManagerCallbacks
14  /**
15   * Electron.DownloadURLOptions to pass to the downloadURL method
16   *
17   * @see https://www.electronjs.org/docs/latest/api/session#sesdownloadurlurl-options
18   */
19  downloadURLOptions?: Electron.DownloadURLOptions
20  /**
21   * If defined, will show a save dialog when the user
22   * downloads a file.
23   *
24   * @see https://www.electronjs.org/docs/latest/api/dialog#dialogshowsavedialogbrowserwindow-options
25   */
26  saveDialogOptions?: SaveDialogOptions
27  /**
28   * The filename to save the file as. If not defined, the filename
29   * from the server will be used.
30   *
31   * Only applies if saveDialogOptions is not defined.
32   */
33  saveAsFilename?: string
34  /**
35   * The directory to save the file to. Must be an absolute path.
36   * @default The user's downloads directory
37   */
38  directory?: string
39  /**
40   * If true, will overwrite the file if it already exists
41   * @default false
42   */
43  overwrite?: boolean
44}

Interface: DownloadManagerCallbacks

1interface DownloadManagerCallbacks {
2  /**
3   * When the download has started. When using a "save as" dialog,
4   * this will be called after the user has selected a location.
5   *
6   * This will always be called first before the progress and completed events.
7   */
8  onDownloadStarted: (data: DownloadData) => void
9  /**
10   * When there is a progress update on a download. Note: This
11   * may be skipped entirely in some cases, where the download
12   * completes immediately. In that case, onDownloadCompleted
13   * will be called instead.
14   */
15  onDownloadProgress: (data: DownloadData) => void
16  /**
17   * When the download has completed
18   */
19  onDownloadCompleted: (data: DownloadData) => void
20  /**
21   * When the download has been cancelled. Also called if the user cancels
22   * from the save as dialog.
23   */
24  onDownloadCancelled: (data: DownloadData) => void
25  /**
26   * When the download has been interrupted. This could be due to a bad
27   * connection, the server going down, etc.
28   */
29  onDownloadInterrupted: (data: DownloadData) => void
30  /**
31   * When an error has been encountered.
32   * Note: The signature is (error, <maybe some data>).
33   */
34  onError: (error: Error, data?: DownloadData) => void
35}

cancelDownload()

Cancels a download.

1cancelDownload(id: string): void

pauseDownload()

Pauses a download.

1pauseDownload(id: string): void

resumeDownload()

Resumes a download.

1resumeDownload(id: string): void

getActiveDownloadCount()

Returns the number of active downloads.

1getActiveDownloadCount(): number

getDownloadData()

Returns the download data for a download.

1getDownloadData(id: string): DownloadData

Class: DownloadData

Data returned in the callbacks for a download.

Properties

1class DownloadData {
2  /**
3   * Generated id for the download
4   */
5  id: string
6  /**
7   * The Electron.DownloadItem. Use this to grab the filename, path, etc.
8   * @see https://www.electronjs.org/docs/latest/api/download-item
9   */
10  item: DownloadItem
11  /**
12   * The Electron.WebContents
13   * @see https://www.electronjs.org/docs/latest/api/web-contents
14   */
15  webContents: WebContents
16  /**
17   * The Electron.Event
18   * @see https://www.electronjs.org/docs/latest/api/event
19   */
20  event: Event
21  /**
22   * The name of the file that is being saved to the user's computer.
23   * Recommended over Item.getFilename() as it may be inaccurate when using the save as dialog.
24   */
25  resolvedFilename: string
26  /**
27   * If true, the download was cancelled from the save as dialog. This flag
28   * will also be true if the download was cancelled by the application when
29   * using the save as dialog.
30   */
31  cancelledFromSaveAsDialog?: boolean
32  /**
33   * The percentage of the download that has been completed
34   */
35  percentCompleted: number
36  /**
37   * The download rate in bytes per second.
38   */
39  downloadRateBytesPerSecond: number
40  /**
41   * The estimated time remaining in seconds.
42   */
43  estimatedTimeRemainingSeconds: number
44  /**
45   * If the download was interrupted, the state in which it was interrupted from
46   */
47  interruptedVia?: 'in-progress' | 'completed'
48}

Formatting download progress

You can use the libraries bytes and dayjs to format the download progress.

1$ npm install bytes dayjs
2$ npm install @types/bytes --save-dev

1import bytes from 'bytes'
2import dayjs from 'dayjs'
3import relativeTime from 'dayjs/plugin/relativeTime';
4import duration from 'dayjs/plugin/duration';
5
6dayjs.extend(relativeTime);
7dayjs.extend(duration);
8
9const downloadData = manager.getDownloadData(id); // or DataItem from the callbacks
10
11// Will return something like 1.2 MB/s
12const formattedDownloadRate = bytes(downloadData.downloadRateBytesPerSecond, { unitSeparator: ' ' }) + '/s'
13
14// Will return something like "in a few seconds"
15const formattedEstimatedTimeRemaining = dayjs.duration(downloadData.estimatedTimeRemainingSeconds, 'seconds').humanize(true)

isDownloadInProgress()

Returns true if the download is in progress.

1isDownloadInProgress(): boolean

isDownloadPaused()

Returns true if the download is paused.

1isDownloadPaused(): boolean

isDownloadResumable()

Returns true if the download is resumable.

1isDownloadResumable(): boolean

isDownloadCancelled()

Returns true if the download is cancelled.

1isDownloadCancelled(): boolean

isDownloadInterrupted()

Returns true if the download is interrupted.

1isDownloadInterrupted(): boolean

isDownloadCompleted()

Returns true if the download is completed.

1isDownloadCompleted(): boolean

Mock class

If you need to mock out ElectronDownloadManager in your tests, you can use the ElectronDownloadManagerMock class.

import { ElectronDownloadManagerMock } from 'electron-dl-manager'

FAQ

How do I capture if the download is invalid? onError() is not being called.

Electron DownloadItem doesn't provide an explicit way to capture errors for downloads in general:

https://www.electronjs.org/docs/latest/api/download-item#class-downloaditem

(It only has on('updated') and on('done') events, which this library uses for defining the callback handlers.)

What it does for invalid URLs, it will trigger the onDownloadCancelled() callback.

1const id = await manager.download({
2  window: mainWindow,
3  url: 'https://alkjsdflksjdflk.com/file.zip',
4  callbacks: {
5    onDownloadCancelled: async (...) => {
6      // Invalid download; this callback will be called
7    },
8  }
9});

A better way to handle this is to check if the URL exists prior to the download yourself. I couldn't find a library that I felt was reliable to include into this package, so it's best you find a library that works for you:

• https://www.npmjs.com/search?q=url%20exists&ranking=maintenance

GPT also suggests the following code (untested):

1async function urlExists(url: string): Promise<boolean> {
2  try {
3    const response = await fetch(url, { method: 'HEAD' });
4    return response.ok;
5  } catch (error) {
6    return false;
7  }
8}
9
10const exists = await urlExists('https://example.com/file.jpg');

Acknowledgments

This code uses small portions from electron-dl and is noted in the code where it is used.

electron-dl is licensed under the MIT License and is maintained by Sindre Sorhus sindresorhus@gmail.com (https://sindresorhus.com).