├── .editorconfig ├── .gitattributes ├── .github └── workflows │ └── main.yml ├── .gitignore ├── .npmrc ├── index.d.ts ├── index.js ├── lib ├── samples.js └── server.js ├── license ├── mock ├── fixtures │ └── electron-master.zip └── index.html ├── package.json ├── readme.md ├── run.js ├── screenshot.png ├── test.html └── test └── index.js /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = tab 5 | end_of_line = lf 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | 10 | [*.yml] 11 | indent_style = space 12 | indent_size = 2 13 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: 3 | - push 4 | - pull_request 5 | jobs: 6 | test: 7 | name: Node.js ${{ matrix.node-version }} 8 | runs-on: macos-latest 9 | strategy: 10 | fail-fast: false 11 | matrix: 12 | node-version: 13 | - 20 14 | - 18 15 | steps: 16 | - uses: actions/checkout@v4 17 | - uses: actions/setup-node@v4 18 | with: 19 | node-version: ${{ matrix.node-version }} 20 | - run: npm install 21 | - run: npm test 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | yarn.lock 3 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /index.d.ts: -------------------------------------------------------------------------------- 1 | import { 2 | type BrowserView, 3 | type BrowserWindow, 4 | type DownloadItem, 5 | type SaveDialogOptions, 6 | } from 'electron'; 7 | 8 | export type Progress = { 9 | percent: number; 10 | transferredBytes: number; 11 | totalBytes: number; 12 | }; 13 | 14 | export type File = { 15 | filename: string; 16 | path: string; 17 | fileSize: number; 18 | mimeType: string; 19 | url: string; 20 | }; 21 | 22 | export type Options = { 23 | /** 24 | Show a `Save As…` dialog instead of downloading immediately. 25 | 26 | Note: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience. 27 | 28 | @default false 29 | */ 30 | readonly saveAs?: boolean; 31 | 32 | /** 33 | The directory to save the file in. 34 | 35 | Must be an absolute path. 36 | 37 | Default: [User's downloads directory](https://electronjs.org/docs/api/app/#appgetpathname) 38 | */ 39 | readonly directory?: string; 40 | 41 | /** 42 | Name of the saved file. 43 | This option only makes sense for `electronDl.download()`. 44 | 45 | Default: [`downloadItem.getFilename()`](https://electronjs.org/docs/api/download-item/#downloaditemgetfilename) 46 | */ 47 | readonly filename?: string; 48 | 49 | /** 50 | Title of the error dialog. Can be customized for localization. 51 | 52 | Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually. 53 | 54 | @default 'Download Error' 55 | */ 56 | readonly errorTitle?: string; 57 | 58 | /** 59 | Message of the error dialog. `{filename}` is replaced with the name of the actual file. Can be customized for localization. 60 | 61 | Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually. 62 | 63 | @default 'The download of {filename} was interrupted' 64 | */ 65 | readonly errorMessage?: string; 66 | 67 | /** 68 | Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item). 69 | You can use this for advanced handling such as canceling the item like `item.cancel()`. 70 | */ 71 | readonly onStarted?: (item: DownloadItem) => void; 72 | 73 | /** 74 | Optional callback that receives an object containing information about the progress of the current download item. 75 | */ 76 | readonly onProgress?: (progress: Progress) => void; 77 | 78 | /** 79 | Optional callback that receives an object containing information about the combined progress of all download items done within any registered window. 80 | 81 | Each time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again. 82 | This callback provides the same data that is used for the progress bar on the app icon. 83 | */ 84 | readonly onTotalProgress?: (progress: Progress) => void; 85 | 86 | /** 87 | Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item) for which the download has been cancelled. 88 | */ 89 | readonly onCancel?: (item: DownloadItem) => void; 90 | 91 | /** 92 | Optional callback that receives an object with information about an item that has been completed. It is called for each completed item. 93 | */ 94 | readonly onCompleted?: (file: File) => void; 95 | 96 | /** 97 | Reveal the downloaded file in the system file manager, and if possible, select the file. 98 | 99 | @default false 100 | */ 101 | readonly openFolderWhenDone?: boolean; 102 | 103 | /** 104 | Show a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress. 105 | 106 | @default true 107 | */ 108 | readonly showBadge?: boolean; 109 | 110 | /** 111 | Show a progress bar on the dock/taskbar icon when a download is in progress. 112 | 113 | @default true 114 | */ 115 | readonly showProgressBar?: boolean; 116 | 117 | /** 118 | Allow downloaded files to overwrite files with the same name in the directory they are saved to. 119 | 120 | The default behavior is to append a number to the filename. 121 | 122 | @default false 123 | */ 124 | readonly overwrite?: boolean; 125 | 126 | /** 127 | Customize the save dialog. 128 | 129 | If `defaultPath` is not explicity defined, a default value is assigned based on the file path. 130 | 131 | @default {} 132 | */ 133 | readonly dialogOptions?: SaveDialogOptions; 134 | }; 135 | 136 | /** 137 | Error thrown if `item.cancel()` was called. 138 | */ 139 | export class CancelError extends Error {} 140 | 141 | /** 142 | Register the helper for all windows. 143 | 144 | @example 145 | ``` 146 | import {app, BrowserWindow} from 'electron'; 147 | import electronDl from 'electron-dl'; 148 | 149 | electronDl(); 150 | 151 | let mainWindow; 152 | (async () => { 153 | await app.whenReady(); 154 | mainWindow = new BrowserWindow(); 155 | })(); 156 | ``` 157 | */ 158 | export default function electronDl(options?: Options): void; 159 | 160 | /** 161 | This can be useful if you need download functionality in a reusable module. 162 | 163 | @param window - Window to register the behavior on. 164 | @param url - URL to download. 165 | @returns A promise for the downloaded file. 166 | @throws {CancelError} An error if the user calls `item.cancel()`. 167 | @throws {Error} An error if the download fails. 168 | 169 | @example 170 | ``` 171 | import {BrowserWindow, ipcMain} from 'electron'; 172 | import {download} from 'electron-dl'; 173 | 174 | ipcMain.on('download-button', async (event, {url}) => { 175 | const win = BrowserWindow.getFocusedWindow(); 176 | console.log(await download(win, url)); 177 | }); 178 | ``` 179 | */ 180 | export function download( 181 | window: BrowserWindow | BrowserView, 182 | url: string, 183 | options?: Options 184 | ): Promise; 185 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | import process from 'node:process'; 2 | import path from 'node:path'; 3 | import { 4 | app, 5 | BrowserWindow, 6 | shell, 7 | dialog, 8 | } from 'electron'; 9 | import {unusedFilenameSync} from 'unused-filename'; 10 | import pupa from 'pupa'; 11 | import extName from 'ext-name'; 12 | 13 | export class CancelError extends Error {} 14 | 15 | const getFilenameFromMime = (name, mime) => { 16 | const extensions = extName.mime(mime); 17 | 18 | if (extensions.length !== 1) { 19 | return name; 20 | } 21 | 22 | return `${name}.${extensions[0].ext}`; 23 | }; 24 | 25 | function registerListener(session, options, callback = () => {}) { 26 | const downloadItems = new Set(); 27 | let receivedBytes = 0; 28 | let completedBytes = 0; 29 | let totalBytes = 0; 30 | const activeDownloadItems = () => downloadItems.size; 31 | const progressDownloadItems = () => receivedBytes / totalBytes; 32 | 33 | options = { 34 | showBadge: true, 35 | showProgressBar: true, 36 | ...options, 37 | }; 38 | 39 | const listener = (event, item, webContents) => { 40 | downloadItems.add(item); 41 | totalBytes += item.getTotalBytes(); 42 | 43 | const window_ = BrowserWindow.fromWebContents(webContents); 44 | if (!window_) { 45 | throw new Error('Failed to get window from web contents.'); 46 | } 47 | 48 | if (options.directory && !path.isAbsolute(options.directory)) { 49 | throw new Error('The `directory` option must be an absolute path'); 50 | } 51 | 52 | const directory = options.directory ?? app.getPath('downloads'); 53 | 54 | let filePath; 55 | if (options.filename) { 56 | filePath = path.join(directory, options.filename); 57 | } else { 58 | const filename = item.getFilename(); 59 | const name = path.extname(filename) ? filename : getFilenameFromMime(filename, item.getMimeType()); 60 | 61 | filePath = options.overwrite ? path.join(directory, name) : unusedFilenameSync(path.join(directory, name)); 62 | } 63 | 64 | const errorMessage = options.errorMessage ?? 'The download of {filename} was interrupted'; 65 | 66 | if (options.saveAs) { 67 | item.setSaveDialogOptions({defaultPath: filePath, ...options.dialogOptions}); 68 | } else { 69 | item.setSavePath(filePath); 70 | } 71 | 72 | item.on('updated', () => { 73 | receivedBytes = completedBytes; 74 | for (const item of downloadItems) { 75 | receivedBytes += item.getReceivedBytes(); 76 | } 77 | 78 | if (options.showBadge && ['darwin', 'linux'].includes(process.platform)) { 79 | app.badgeCount = activeDownloadItems(); 80 | } 81 | 82 | if (!window_.isDestroyed() && options.showProgressBar) { 83 | window_.setProgressBar(progressDownloadItems()); 84 | } 85 | 86 | if (typeof options.onProgress === 'function') { 87 | const itemTransferredBytes = item.getReceivedBytes(); 88 | const itemTotalBytes = item.getTotalBytes(); 89 | 90 | options.onProgress({ 91 | percent: itemTotalBytes ? itemTransferredBytes / itemTotalBytes : 0, 92 | transferredBytes: itemTransferredBytes, 93 | totalBytes: itemTotalBytes, 94 | }); 95 | } 96 | 97 | if (typeof options.onTotalProgress === 'function') { 98 | options.onTotalProgress({ 99 | percent: progressDownloadItems(), 100 | transferredBytes: receivedBytes, 101 | totalBytes, 102 | }); 103 | } 104 | }); 105 | 106 | item.on('done', (event, state) => { 107 | completedBytes += item.getTotalBytes(); 108 | downloadItems.delete(item); 109 | 110 | if (options.showBadge && ['darwin', 'linux'].includes(process.platform)) { 111 | app.badgeCount = activeDownloadItems(); 112 | } 113 | 114 | if (!window_.isDestroyed() && !activeDownloadItems()) { 115 | window_.setProgressBar(-1); 116 | receivedBytes = 0; 117 | completedBytes = 0; 118 | totalBytes = 0; 119 | } 120 | 121 | if (options.unregisterWhenDone) { 122 | session.removeListener('will-download', listener); 123 | } 124 | 125 | // eslint-disable-next-line unicorn/prefer-switch 126 | if (state === 'cancelled') { 127 | if (typeof options.onCancel === 'function') { 128 | options.onCancel(item); 129 | } 130 | 131 | callback(new CancelError()); 132 | } else if (state === 'interrupted') { 133 | const message = pupa(errorMessage, {filename: path.basename(filePath)}); 134 | callback(new Error(message)); 135 | } else if (state === 'completed') { 136 | const savePath = item.getSavePath(); 137 | 138 | if (process.platform === 'darwin') { 139 | app.dock.downloadFinished(savePath); 140 | } 141 | 142 | if (options.openFolderWhenDone) { 143 | shell.showItemInFolder(savePath); 144 | } 145 | 146 | if (typeof options.onCompleted === 'function') { 147 | options.onCompleted({ 148 | fileName: item.getFilename(), // Just for backwards compatibility. TODO: Remove in the next major version. 149 | filename: item.getFilename(), 150 | path: savePath, 151 | fileSize: item.getReceivedBytes(), 152 | mimeType: item.getMimeType(), 153 | url: item.getURL(), 154 | }); 155 | } 156 | 157 | callback(null, item); 158 | } 159 | }); 160 | 161 | if (typeof options.onStarted === 'function') { 162 | options.onStarted(item); 163 | } 164 | }; 165 | 166 | session.on('will-download', listener); 167 | } 168 | 169 | export default function electronDl(options = {}) { 170 | app.on('session-created', session => { 171 | registerListener(session, options, (error, _) => { 172 | if (error && !(error instanceof CancelError)) { 173 | const errorTitle = options.errorTitle ?? 'Download Error'; 174 | dialog.showErrorBox(errorTitle, error.message); 175 | } 176 | }); 177 | }); 178 | } 179 | 180 | export async function download(window_, url, options) { 181 | return new Promise((resolve, reject) => { 182 | options = { 183 | ...options, 184 | unregisterWhenDone: true, 185 | }; 186 | 187 | registerListener(window_.webContents.session, options, (error, item) => { 188 | if (error) { 189 | reject(error); 190 | } else { 191 | resolve(item); 192 | } 193 | }); 194 | 195 | window_.webContents.downloadURL(url); 196 | }); 197 | } 198 | -------------------------------------------------------------------------------- /lib/samples.js: -------------------------------------------------------------------------------- 1 | import path from 'node:path'; 2 | import {randomUUID} from 'node:crypto'; 3 | import fs from 'node:fs'; 4 | import {fileURLToPath} from 'node:url'; 5 | import pify from 'pify'; 6 | import {copyFile} from 'copy-file'; 7 | 8 | const __dirname = path.dirname(fileURLToPath(import.meta.url)); 9 | 10 | const fixtureDirectory = path.join(__dirname, '../mock/fixtures'); 11 | 12 | export const setup = async numberFiles => { 13 | const promises = []; 14 | const files = []; 15 | 16 | while (files.length < numberFiles) { 17 | const filename = `${randomUUID()}.zip`; 18 | promises.push(copyFile(path.join(fixtureDirectory, 'electron-master.zip'), path.join(fixtureDirectory, filename))); 19 | files.push(filename); 20 | } 21 | 22 | await Promise.all(promises); 23 | 24 | return files; 25 | }; 26 | 27 | export const teardown = async () => { 28 | const files = await pify(fs.readdir)(fixtureDirectory); 29 | const promises = []; 30 | 31 | for (const file of files) { 32 | console.log(path.join(fixtureDirectory, file)); 33 | if (file !== 'electron-master.zip') { 34 | promises.push(pify(fs.unlink)(path.join(fixtureDirectory, file))); 35 | } 36 | } 37 | 38 | return Promise.all(promises); 39 | }; 40 | 41 | -------------------------------------------------------------------------------- /lib/server.js: -------------------------------------------------------------------------------- 1 | import http from 'node:http'; 2 | import nodeStatic from 'node-static'; 3 | 4 | const server = () => { 5 | const fileServer = new nodeStatic.Server('./mock', {cache: false}); 6 | 7 | http.createServer((request, response) => { 8 | request.addListener('end', () => { 9 | fileServer.serve(request, response); 10 | }).resume(); 11 | }).listen(8080); 12 | }; 13 | 14 | export default server; 15 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Sindre Sorhus (https://sindresorhus.com) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | -------------------------------------------------------------------------------- /mock/fixtures/electron-master.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sindresorhus/electron-dl/972398c4eb47cdc58379e4ef662f0a92e94e6718/mock/fixtures/electron-master.zip -------------------------------------------------------------------------------- /mock/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "electron-dl", 3 | "version": "4.0.0", 4 | "description": "Simplified file downloads for your Electron app", 5 | "license": "MIT", 6 | "repository": "sindresorhus/electron-dl", 7 | "funding": "https://github.com/sponsors/sindresorhus", 8 | "author": { 9 | "name": "Sindre Sorhus", 10 | "email": "sindresorhus@gmail.com", 11 | "url": "https://sindresorhus.com" 12 | }, 13 | "type": "module", 14 | "exports": { 15 | "types": "./index.d.ts", 16 | "default": "./index.js" 17 | }, 18 | "sideEffects": false, 19 | "engines": { 20 | "node": ">=18" 21 | }, 22 | "scripts": { 23 | "start": "electron run.js", 24 | "//test": "xo && ava && tsc index.d.ts", 25 | "test": "xo && tsc index.d.ts" 26 | }, 27 | "files": [ 28 | "index.js", 29 | "index.d.ts" 30 | ], 31 | "keywords": [ 32 | "electron", 33 | "app", 34 | "file", 35 | "download", 36 | "downloader", 37 | "progress" 38 | ], 39 | "dependencies": { 40 | "ext-name": "^5.0.0", 41 | "pupa": "^3.1.0", 42 | "unused-filename": "^4.0.1" 43 | }, 44 | "devDependencies": { 45 | "@types/node": "^20.12.7", 46 | "ava": "^6.1.2", 47 | "copy-file": "^11.0.0", 48 | "electron": "^30.0.1", 49 | "minimist": "^1.2.8", 50 | "node-static": "^0.7.11", 51 | "pify": "^6.1.0", 52 | "spectron": "^19.0.0", 53 | "typescript": "^5.4.5", 54 | "xo": "^0.58.0" 55 | }, 56 | "xo": { 57 | "envs": [ 58 | "node", 59 | "browser" 60 | ] 61 | }, 62 | "ava": { 63 | "serial": true 64 | } 65 | } 66 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # electron-dl 2 | 3 | > Simplified file downloads for your [Electron](https://electronjs.org) app 4 | 5 | ## Why? 6 | 7 | - One function call instead of having to manually implement a lot of [boilerplate](index.js). 8 | - Saves the file to the users Downloads directory instead of prompting. 9 | - Bounces the Downloads directory in the dock when done. *(macOS)* 10 | - Handles multiple downloads. 11 | - Shows badge count *(macOS & Linux only)* and download progress. Example on macOS: 12 | 13 | 14 | 15 | ## Install 16 | 17 | ```sh 18 | npm install electron-dl 19 | ``` 20 | 21 | *Requires Electron 30 or later.* 22 | 23 | ## Usage 24 | 25 | ### Register it for all windows 26 | 27 | This is probably what you want for your app. 28 | 29 | ```js 30 | import {app, BrowserWindow} from 'electron'; 31 | import electronDl from 'electron-dl'; 32 | 33 | electronDl(); 34 | 35 | let mainWindow; 36 | (async () => { 37 | await app.whenReady(); 38 | mainWindow = new BrowserWindow(); 39 | })(); 40 | ``` 41 | 42 | ### Use it manually 43 | 44 | This can be useful if you need download functionality in a reusable module. 45 | 46 | ```js 47 | import {BrowserWindow, ipcMain} from 'electron'; 48 | import {download, CancelError} from 'electron-dl'; 49 | 50 | ipcMain.on('download-button', async (event, {url}) => { 51 | const win = BrowserWindow.getFocusedWindow(); 52 | try { 53 | console.log(await download(win, url)); 54 | } catch (error) { 55 | if (error instanceof CancelError) { 56 | console.info('item.cancel() was called'); 57 | } else { 58 | console.error(error); 59 | } 60 | } 61 | }); 62 | ``` 63 | 64 | ## API 65 | 66 | It can only be used in the [main](https://electronjs.org/docs/glossary/#main-process) process. 67 | 68 | ### electronDl(options?) 69 | 70 | ### download(window, url, options?): Promise<[DownloadItem](https://electronjs.org/docs/api/download-item)> 71 | 72 | ### window 73 | 74 | Type: `BrowserWindow | WebContentsView` 75 | 76 | The window to register the behavior on. Alternatively, a `WebContentsView` can be passed. 77 | 78 | ### url 79 | 80 | Type: `string` 81 | 82 | The URL to download. 83 | 84 | ### options 85 | 86 | Type: `object` 87 | 88 | #### saveAs 89 | 90 | Type: `boolean`\ 91 | Default: `false` 92 | 93 | Show a `Save As…` dialog instead of downloading immediately. 94 | 95 | Note: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience. 96 | 97 | #### directory 98 | 99 | Type: `string`\ 100 | Default: [User's downloads directory](https://electronjs.org/docs/api/app/#appgetpathname) 101 | 102 | The directory to save the file in. 103 | 104 | Must be an absolute path. 105 | 106 | #### filename 107 | 108 | Type: `string`\ 109 | Default: [`downloadItem.getFilename()`](https://electronjs.org/docs/api/download-item/#downloaditemgetfilename) 110 | 111 | Name of the saved file. 112 | 113 | This option only makes sense for `electronDl.download()`. 114 | 115 | #### errorTitle 116 | 117 | Type: `string`\ 118 | Default: `'Download Error'` 119 | 120 | Title of the error dialog. Can be customized for localization. 121 | 122 | Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually. 123 | 124 | #### errorMessage 125 | 126 | Type: `string`\ 127 | Default: `'The download of {filename} was interrupted'` 128 | 129 | Message of the error dialog. `{filename}` is replaced with the name of the actual file. Can be customized for localization. 130 | 131 | Note: Error dialog will not be shown in `electronDl.download()`. Please handle error manually. 132 | 133 | #### onStarted 134 | 135 | Type: `Function` 136 | 137 | Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item). 138 | 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. 139 | 140 | #### onProgress 141 | 142 | Type: `Function` 143 | 144 | Optional callback that receives an object containing information about the progress of the current download item. 145 | 146 | ```js 147 | { 148 | percent: 0.1, 149 | transferredBytes: 100, 150 | totalBytes: 1000 151 | } 152 | ``` 153 | 154 | #### onTotalProgress 155 | 156 | Type: `Function` 157 | 158 | Optional callback that receives an object containing information about the combined progress of all download items done within any registered window. 159 | 160 | Each time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again. 161 | This callback provides the same data that is used for the progress bar on the app icon. 162 | 163 | ```js 164 | { 165 | percent: 0.1, 166 | transferredBytes: 100, 167 | totalBytes: 1000 168 | } 169 | ``` 170 | 171 | #### onCancel 172 | 173 | Type: `Function` 174 | 175 | Optional callback that receives the [download item](https://electronjs.org/docs/api/download-item) for which the download has been cancelled. 176 | 177 | #### onCompleted 178 | 179 | Type: `Function` 180 | 181 | Optional callback that receives an object with information about an item that has been completed. It is called for each completed item. 182 | 183 | ```js 184 | { 185 | filename: 'file.zip', 186 | path: '/path/file.zip', 187 | fileSize: 503320, 188 | mimeType: 'application/zip', 189 | url: 'https://example.com/file.zip' 190 | } 191 | ``` 192 | 193 | #### openFolderWhenDone 194 | 195 | Type: `boolean`\ 196 | Default: `false` 197 | 198 | Reveal the downloaded file in the system file manager, and if possible, select the file. 199 | 200 | #### showBadge 201 | 202 | Type: `boolean`\ 203 | Default: `true` 204 | 205 | Show a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress. 206 | 207 | #### showProgressBar 208 | 209 | Type: `boolean`\ 210 | Default: `true` 211 | 212 | Show a progress bar on the dock/taskbar icon when a download is in progress. 213 | 214 | #### overwrite 215 | 216 | Type: `boolean`\ 217 | Default: `false` 218 | 219 | Allow downloaded files to overwrite files with the same name in the directory they are saved to. 220 | 221 | The default behavior is to append a number to the filename. 222 | 223 | #### dialogOptions 224 | 225 | Type: [`SaveDialogOptions`](https://www.electronjs.org/docs/latest/api/download-item#downloaditemsetsavedialogoptionsoptions)\ 226 | Default: `{}` 227 | 228 | Customize the save dialog. 229 | 230 | If `defaultPath` is not explicity defined, a default value is assigned based on the file path. 231 | 232 | ## Development 233 | 234 | After making changes, run the automated tests: 235 | 236 | ```sh 237 | npm test 238 | ``` 239 | 240 | And before submitting a pull request, run the manual tests to manually verify that everything works: 241 | 242 | ```sh 243 | npm start 244 | ``` 245 | 246 | ## Related 247 | 248 | - [electron-debug](https://github.com/sindresorhus/electron-debug) - Adds useful debug features to your Electron app 249 | - [electron-context-menu](https://github.com/sindresorhus/electron-context-menu) - Context menu for your Electron app 250 | - [electron-store](https://github.com/sindresorhus/electron-store) - Save and load data like user settings, app state, cache, etc 251 | - [electron-unhandled](https://github.com/sindresorhus/electron-unhandled) - Catch unhandled errors and promise rejections in your Electron app 252 | -------------------------------------------------------------------------------- /run.js: -------------------------------------------------------------------------------- 1 | import process from 'node:process'; 2 | import { 3 | app, 4 | BrowserWindow, 5 | BaseWindow, 6 | WebContentsView, 7 | } from 'electron'; 8 | import minimist from 'minimist'; 9 | import {setup, teardown} from './lib/samples.js'; 10 | import server from './lib/server.js'; 11 | import electronDl, {download} from './index.js'; 12 | 13 | electronDl(); 14 | 15 | const argv = minimist(process.argv.slice(2)); 16 | 17 | // eslint-disable-next-line unicorn/prefer-top-level-await 18 | (async () => { 19 | await app.whenReady(); 20 | 21 | server(); 22 | 23 | const win = new BrowserWindow({ 24 | webPreferences: { 25 | nodeIntegration: true, 26 | }, 27 | }); 28 | 29 | win.on('closed', teardown); 30 | 31 | win.webContents.session.enableNetworkEmulation({ 32 | latency: 2, 33 | downloadThroughput: 1024 * 1024, 34 | }); 35 | 36 | const numberSampleFiles = 'files' in argv ? argv.files : 5; 37 | const files = await setup(numberSampleFiles); 38 | await win.loadURL(`http://localhost:8080/index.html?files=${JSON.stringify(files)}`); 39 | 40 | // Test 1 41 | await download(BrowserWindow.getFocusedWindow(), 'https://google.com'); 42 | 43 | // Test 2 44 | const win2 = new BaseWindow({width: 800, height: 400}); 45 | const view = new WebContentsView(); 46 | win2.contentView.addChildView(view); 47 | await view.webContents.loadURL('https://electronjs.org'); 48 | await download(view, 'https://google.com'); 49 | })(); 50 | 51 | process.on('SIGINT', teardown); 52 | -------------------------------------------------------------------------------- /screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sindresorhus/electron-dl/972398c4eb47cdc58379e4ef662f0a92e94e6718/screenshot.png -------------------------------------------------------------------------------- /test.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Here be unicorns 5 | 6 | 7 | -------------------------------------------------------------------------------- /test/index.js: -------------------------------------------------------------------------------- 1 | import fs from 'node:fs'; 2 | import path from 'node:path'; 3 | import {fileURLToPath} from 'node:url'; 4 | import test from 'ava'; 5 | import pify from 'pify'; 6 | import {Application} from 'spectron'; 7 | 8 | const __dirname = path.dirname(fileURLToPath(import.meta.url)); 9 | 10 | test.beforeEach(async t => { 11 | t.context.spectron = new Application({ 12 | path: 'node_modules/.bin/electron', 13 | args: [ 14 | 'run.js', 15 | '--files=3', 16 | ], 17 | }); 18 | await t.context.spectron.start(); 19 | }); 20 | 21 | test.beforeEach(async t => { 22 | const files = await pify(fs.readdir)(path.join(__dirname, '../mock/fixtures')); 23 | t.context.files = files.filter(file => file !== 'electron-master.zip'); 24 | }); 25 | 26 | test.afterEach.always(async t => { 27 | await t.context.spectron.stop(); 28 | }); 29 | 30 | test('download a single file', async t => { 31 | const {client} = t.context.spectron; 32 | await client.waitUntilWindowLoaded(); 33 | await client.url(`http://localhost:8080/index.html?files=${JSON.stringify(t.context.files)}`); 34 | await client.waitForExist(`[data-unique-filename="${t.context.files[0]}"]`); 35 | await client.click(`[data-unique-filename="${t.context.files[0]}"]`); 36 | 37 | t.is(await t.context.spectron.electron.remote.app.badgeCount(), 1); 38 | }); 39 | 40 | test('download a couple files', async t => { 41 | const {client} = t.context.spectron; 42 | await client.waitUntilWindowLoaded(); 43 | await client.url(`http://localhost:8080/index.html?files=${JSON.stringify(t.context.files)}`); 44 | await client.waitForExist(`[data-unique-filename="${t.context.files[1]}"]`); 45 | await client.waitForExist(`[data-unique-filename="${t.context.files[2]}"]`); 46 | await client.click(`[data-unique-filename="${t.context.files[1]}"]`); 47 | await client.click(`[data-unique-filename="${t.context.files[2]}"]`); 48 | 49 | // The first download appears to finish before the second is added sometimes 50 | const badgeCount = await t.context.spectron.electron.remote.app.badgeCount(); 51 | t.true(badgeCount === 1 || badgeCount === 2); 52 | }); 53 | --------------------------------------------------------------------------------