electron-dl

Simplified file downloads for your Electron app

Why?

• One function call instead of having to manually implement a lot of boilerplate.
• Saves the file to the users Downloads directory instead of prompting.
• Bounces the Downloads directory in the dock when done. (macOS)
• Handles multiple downloads.
• Resumes interrupted downloads when the server supports it, while the app is running.
• Shows badge count (macOS & Linux only) and download progress. Example on macOS:

Install

npm install electron-dl

Requires Electron 44 or later.

Usage

Register it for all windows

This is probably what you want for your app.

import {app, BrowserWindow} from 'electron';
import electronDl from 'electron-dl';

electronDl();

let mainWindow;
(async () => {
	await app.whenReady();
	mainWindow = new BrowserWindow();
})();

Use it manually

This can be useful if you need download functionality in a reusable module.

import {BrowserWindow, ipcMain} from 'electron';
import {download, CancelError} from 'electron-dl';

ipcMain.on('download-button', async (event, {url}) => {
	const win = BrowserWindow.getFocusedWindow();
	try {
		console.log(await download(win, url));
	} catch (error) {
		if (error instanceof CancelError) {
			console.info('item.cancel() was called');
		} else {
			console.error(error);
		}
	}
});

Download into memory

This can be useful if you want to process a file without saving it to disk first.

import {BrowserWindow, ipcMain} from 'electron';
import {downloadAsBytes} from 'electron-dl';

ipcMain.on('download-button', async (event, {url}) => {
	const win = BrowserWindow.getFocusedWindow();
	const bytes = await downloadAsBytes(win, url);
	console.log(bytes.length);
});

API

It can only be used in the main process.

electronDl(options?)

download(window, url, options?): Promise<DownloadItem>

Multiple calls can be in progress at the same time. Each call handles its own download.

An interrupted download is resumed automatically when the server supports it, as long as the app is running. A download is not resumed after the app is restarted, since that would need the app to persist the download state.

window

Type: BrowserWindow | WebContentsView

The window to register the behavior on. Alternatively, a WebContentsView can be passed.

url

Type: string

The URL to download.

options

Type: object

saveAs

Type: boolean
Default: false

Show a Save As… dialog instead of downloading immediately.

Note: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience.

directory

Type: string
Default: User's downloads directory

The directory to save the file in.

Must be an absolute path.

filename

Type: string
Default: downloadItem.getFilename()

Name of the saved file.

Must not contain a path separator, so it cannot point outside directory.

This option only makes sense for electronDl.download().

errorTitle

Type: string
Default: 'Download Error'

Title of the error dialog. Can be customized for localization.

Note: Error dialog will not be shown in electronDl.download(). Please handle error manually.

errorMessage

Type: string
Default: 'The download of {filename} was interrupted'

Message of the error dialog. {filename} is replaced with the name of the actual file. Can be customized for localization.

Note: Error dialog will not be shown in electronDl.download(). Please handle error manually.

onStarted

Type: Function

Optional callback that receives the download item. You can use this for advanced handling such as canceling the item like item.cancel() which will throw electronDl.CancelError from the electronDl.download() method.

onProgress

Type: Function

Optional callback that receives an object containing information about the progress of the current download item.

{
	percent: 0.1,
	transferredBytes: 100,
	totalBytes: 1000
}

onTotalProgress

Type: Function

Optional callback that receives an object containing information about the combined progress of all download items done within any registered window.

Each time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again. This callback provides the same data that is used for the progress bar on the app icon.

{
	percent: 0.1,
	transferredBytes: 100,
	totalBytes: 1000
}

onCancel

Type: Function

Optional callback that receives the download item for which the download has been cancelled.

onCompleted

Type: Function

Optional callback that receives an object with information about an item that has been completed. It is called for each completed item.

{
	filename: 'file.zip',
	path: '/path/file.zip',
	fileSize: 503320,
	mimeType: 'application/zip',
	url: 'https://example.com/file.zip'
}

onError

Type: Function

Optional callback that receives the Error for a download that was interrupted and could not be resumed.

When this is provided, the error dialog is not shown. Use this to show your own error dialog or to handle the failure in another way.

This option only makes sense for the default export. electronDl.download() rejects with the error instead.

import electronDl from 'electron-dl';

electronDl({
	onError(error) {
		console.error(error.message);
	}
});

openFolderWhenDone

Type: boolean
Default: false

Reveal the downloaded file in the system file manager, and if possible, select the file.

showBadge

Type: boolean
Default: true

Show a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress.

showProgressBar

Type: boolean
Default: true

Show a progress bar on the dock/taskbar icon when a download is in progress.

Downloads without an associated BrowserWindow are saved normally, but do not show a progress bar.

overwrite

Type: boolean
Default: false

Allow downloaded files to overwrite files with the same name in the directory they are saved to.

The default behavior is to append a number to the filename.

dialogOptions

Type: SaveDialogOptions
Default: {}

Customize the save dialog.

If defaultPath is not explicity defined, a default value is assigned based on the file path.

downloadAsBytes(window, url, options?): Promise<Uint8Array>

Download a file into memory instead of saving it to disk. Use this when you want to process the file directly.

The download does not appear in the Downloads directory. It is not shown in the dock/taskbar badge or progress bar, and it cannot be resumed.

The promise rejects when the server responds with an error status.

window and url are the same as for download().

onProgress

Type: Function

Optional callback that receives an object containing information about the progress of the download.

{
	percent: 0.1,
	transferredBytes: 100,
	totalBytes: 1000
}

percent is 0 when the total size is not known, for example for a compressed or chunked response.

signal

Type: AbortSignal

An AbortSignal to cancel the download with. An aborted download rejects with the signal's abort reason, which defaults to an AbortError.

Development

After making changes, run the automated tests:

npm test

And before submitting a pull request, run the manual tests to manually verify that everything works:

npm start

Related

• electron-debug - Adds useful debug features to your Electron app
• electron-context-menu - Context menu for your Electron app
• electron-store - Save and load data like user settings, app state, cache, etc
• electron-unhandled - Catch unhandled errors and promise rejections in your Electron app