1 | # @electron/get
|
2 |
|
3 | > Download Electron release artifacts
|
4 |
|
5 | [![CircleCI](https://circleci.com/gh/electron/get.svg?style=svg)](https://circleci.com/gh/electron/get)
|
6 |
|
7 | ## Usage
|
8 |
|
9 | ### Simple: Downloading an Electron Binary ZIP
|
10 |
|
11 | ```typescript
|
12 | import { download } from '@electron/get';
|
13 |
|
14 | // NB: Use this syntax within an async function, Node does not have support for
|
15 | // top-level await as of Node 12.
|
16 | const zipFilePath = await download('4.0.4');
|
17 | ```
|
18 |
|
19 | ### Advanced: Downloading a macOS Electron Symbol File
|
20 |
|
21 |
|
22 | ```typescript
|
23 | import { downloadArtifact } from '@electron/get';
|
24 |
|
25 | // NB: Use this syntax within an async function, Node does not have support for
|
26 | // top-level await as of Node 12.
|
27 | const zipFilePath = await downloadArtifact({
|
28 | version: '4.0.4',
|
29 | platform: 'darwin',
|
30 | artifactName: 'electron',
|
31 | artifactSuffix: 'symbols',
|
32 | arch: 'x64',
|
33 | });
|
34 | ```
|
35 |
|
36 | ### Specifying a mirror
|
37 |
|
38 | To specify another location to download Electron assets from, the following options are
|
39 | available:
|
40 |
|
41 | * `mirrorOptions` Object
|
42 | * `mirror` String (optional) - The base URL of the mirror to download from.
|
43 | * `nightlyMirror` String (optional) - The Electron nightly-specific mirror URL.
|
44 | * `customDir` String (optional) - The name of the directory to download from, often scoped by version number.
|
45 | * `customFilename` String (optional) - The name of the asset to download.
|
46 | * `resolveAssetURL` Function (optional) - A function allowing customization of the url used to download the asset.
|
47 |
|
48 | Anatomy of a download URL, in terms of `mirrorOptions`:
|
49 |
|
50 | ```
|
51 | https://github.com/electron/electron/releases/download/v4.0.4/electron-v4.0.4-linux-x64.zip
|
52 | | | | |
|
53 | ------------------------------------------------------- -----------------------------
|
54 | | |
|
55 | mirror / nightlyMirror | | customFilename
|
56 | ------
|
57 | ||
|
58 | customDir
|
59 | ```
|
60 |
|
61 | Example:
|
62 |
|
63 | ```typescript
|
64 | import { download } from '@electron/get';
|
65 |
|
66 | const zipFilePath = await download('4.0.4', {
|
67 | mirrorOptions: {
|
68 | mirror: 'https://mirror.example.com/electron/',
|
69 | customDir: 'custom',
|
70 | customFilename: 'unofficial-electron-linux.zip'
|
71 | }
|
72 | });
|
73 | // Will download from https://mirror.example.com/electron/custom/unofficial-electron-linux.zip
|
74 |
|
75 | const nightlyZipFilePath = await download('8.0.0-nightly.20190901', {
|
76 | mirrorOptions: {
|
77 | nightlyMirror: 'https://nightly.example.com/',
|
78 | customDir: 'nightlies',
|
79 | customFilename: 'nightly-linux.zip'
|
80 | }
|
81 | });
|
82 | // Will download from https://nightly.example.com/nightlies/nightly-linux.zip
|
83 | ```
|
84 |
|
85 | `customDir` can have the placeholder `{{ version }}`, which will be replaced by the version
|
86 | specified (without the leading `v`). For example:
|
87 |
|
88 | ```javascript
|
89 | const zipFilePath = await download('4.0.4', {
|
90 | mirrorOptions: {
|
91 | mirror: 'https://mirror.example.com/electron/',
|
92 | customDir: 'version-{{ version }}',
|
93 | platform: 'linux',
|
94 | arch: 'x64'
|
95 | }
|
96 | });
|
97 | // Will download from https://mirror.example.com/electron/version-4.0.4/electron-v4.0.4-linux-x64.zip
|
98 | ```
|
99 |
|
100 | #### Using environment variables for mirror options
|
101 | Mirror options can also be specified via the following environment variables:
|
102 | * `ELECTRON_CUSTOM_DIR` - Specifies the custom directory to download from.
|
103 | * `ELECTRON_CUSTOM_FILENAME` - Specifies the custom file name to download.
|
104 | * `ELECTRON_MIRROR` - Specifies the URL of the server to download from if the version is not a nightly version.
|
105 | * `ELECTRON_NIGHTLY_MIRROR` - Specifies the URL of the server to download from if the version is a nightly version.
|
106 |
|
107 | ### Overriding the version downloaded
|
108 |
|
109 | The version downloaded can be overriden by setting the `ELECTRON_CUSTOM_VERSION` environment variable.
|
110 | Setting this environment variable will override the version passed in to `download` or `downloadArtifact`.
|
111 |
|
112 | ## How It Works
|
113 |
|
114 | This module downloads Electron to a known place on your system and caches it
|
115 | so that future requests for that asset can be returned instantly. The cache
|
116 | locations are:
|
117 |
|
118 | * Linux: `$XDG_CACHE_HOME` or `~/.cache/electron/`
|
119 | * MacOS: `~/Library/Caches/electron/`
|
120 | * Windows: `%LOCALAPPDATA%/electron/Cache` or `~/AppData/Local/electron/Cache/`
|
121 |
|
122 | By default, the module uses [`got`](https://github.com/sindresorhus/got) as the
|
123 | downloader. As a result, you can use the same [options](https://github.com/sindresorhus/got#options)
|
124 | via `downloadOptions`.
|
125 |
|
126 | ### Progress Bar
|
127 |
|
128 | By default, a progress bar is shown when downloading an artifact for more than 30 seconds. To
|
129 | disable, set the `ELECTRON_GET_NO_PROGRESS` environment variable to any non-empty value, or set
|
130 | `quiet` to `true` in `downloadOptions`. If you need to monitor progress yourself via the API, set
|
131 | `getProgressCallback` in `downloadOptions`, which has the same function signature as `got`'s
|
132 | [`downloadProgress` event callback](https://github.com/sindresorhus/got#ondownloadprogress-progress).
|
133 |
|
134 | ### Proxies
|
135 |
|
136 | Downstream packages should utilize the `initializeProxy` function to add HTTP(S) proxy support. If
|
137 | the environment variable `ELECTRON_GET_USE_PROXY` is set, it is called automatically. A different
|
138 | proxy module is used, depending on the version of Node in use, and as such, there are slightly
|
139 | different ways to set the proxy environment variables. For Node 10 and above,
|
140 | [`global-agent`](https://github.com/gajus/global-agent#environment-variables) is used. Otherwise,
|
141 | [`global-tunnel-ng`](https://github.com/np-maintain/global-tunnel#auto-config) is used. Refer to the
|
142 | appropriate linked module to determine how to configure proxy support.
|