docs(autoUpdater): document static storage strategy (#42755)
* docs: `autoUpdater` static storage strategy * summary must be followed by newline * lint: fix whitespace for code blocks * lint: `js` -> `javascript` * bump * `javascript` -> `js` * bump Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: Erick Zhao <erick@hotmail.ca>
This commit is contained in:
parent
57e859d0af
commit
37fc8346aa
1 changed files with 112 additions and 0 deletions
|
@ -10,6 +10,114 @@ The easiest and officially supported one is taking advantage of the built-in
|
|||
[Squirrel](https://github.com/Squirrel) framework and
|
||||
Electron's [autoUpdater](../api/auto-updater.md) module.
|
||||
|
||||
## Using cloud object storage (serverless)
|
||||
|
||||
For a simple serverless update flow, Electron's autoUpdater module can
|
||||
check if updates are available by pointing to a static storage URL
|
||||
containing latest release metadata.
|
||||
|
||||
When a new release is available, this metadata needs to be published to
|
||||
cloud storage alongside the release itself. The metadata format is
|
||||
different for macOS and Windows.
|
||||
|
||||
### Publishing release metadata
|
||||
|
||||
With Electron Forge, you can set up static file storage updates by publishing
|
||||
metadata artifacts from the ZIP Maker (macOS) with `macUpdateManifestBaseUrl`
|
||||
and the Squirrel.Windows Maker (Windows) with `remoteReleases`.
|
||||
|
||||
See Forge's [Auto updating from S3](https://www.electronforge.io/config/publishers/s3#auto-updating-from-s3)
|
||||
guide for an end-to-end example.
|
||||
|
||||
<details>
|
||||
<summary>Manual publishing</summary>
|
||||
|
||||
On macOS, Squirrel.Mac can receive updates by reading a `releases.json` file with the
|
||||
following JSON format:
|
||||
|
||||
```json title='releases.json'
|
||||
{
|
||||
"currentRelease": "1.2.3",
|
||||
"releases": [
|
||||
{
|
||||
"version": "1.2.1",
|
||||
"updateTo": {
|
||||
"version": "1.2.1",
|
||||
"pub_date": "2023-09-18T12:29:53+01:00",
|
||||
"notes": "Theses are some release notes innit",
|
||||
"name": "1.2.1",
|
||||
"url": "https://mycompany.example.com/myapp/releases/myrelease"
|
||||
}
|
||||
},
|
||||
{
|
||||
"version": "1.2.3",
|
||||
"updateTo": {
|
||||
"version": "1.2.3",
|
||||
"pub_date": "2024-09-18T12:29:53+01:00",
|
||||
"notes": "Theses are some more release notes innit",
|
||||
"name": "1.2.3",
|
||||
"url": "https://mycompany.example.com/myapp/releases/myrelease3"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
On Windows, Squirrel.Windows can receive updates by reading from the RELEASES
|
||||
file generated during the build process. This file details the `.nupkg` delta
|
||||
package to update to.
|
||||
|
||||
```plaintext title='RELEASES'
|
||||
B0892F3C7AC91D72A6271FF36905FEF8FE993520 electron-fiddle-0.36.3-full.nupkg 103298365
|
||||
```
|
||||
|
||||
These files should live in the same directory as your release, under a folder
|
||||
structure that is aware of your app's platform and architecture.
|
||||
|
||||
For example:
|
||||
|
||||
```plaintext
|
||||
my-app-updates/
|
||||
├─ darwin/
|
||||
│ ├─ x64/
|
||||
│ │ ├─ my-app-1.0.0-darwin-x64.zip
|
||||
│ │ ├─ my-app-1.1.0-darwin-x64.zip
|
||||
│ │ ├─ RELEASES.json
|
||||
│ ├─ arm64/
|
||||
│ │ ├─ my-app-1.0.0-darwin-arm64.zip
|
||||
│ │ ├─ my-app-1.1.0-darwin-arm64.zip
|
||||
│ │ ├─ RELEASES.json
|
||||
├─ win32/
|
||||
│ ├─ x64/
|
||||
│ │ ├─ my-app-1.0.0-win32-x64.exe
|
||||
│ │ ├─ my-app-1.0.0-win32-x64.nupkg
|
||||
│ │ ├─ my-app-1.1.0-win32-x64.exe
|
||||
│ │ ├─ my-app-1.1.0-win32-x64.nupkg
|
||||
│ │ ├─ RELEASES
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Reading release metadata
|
||||
|
||||
The easiest way to consume metadata is by installing [update-electron-app][],
|
||||
a drop-in Node.js module that sets up autoUpdater and prompts the user with
|
||||
a native dialog.
|
||||
|
||||
For static storage updates, point the `updateSource.baseUrl` parameter to
|
||||
the directory containing your release metadata files.
|
||||
|
||||
```js title="main.js" @ts-nocheck
|
||||
const { updateElectronApp, UpdateSourceType } = require('update-electron-app')
|
||||
|
||||
updateElectronApp({
|
||||
updateSource: {
|
||||
type: UpdateSourceType.StaticStorage,
|
||||
baseUrl: `https://my-bucket.s3.amazonaws.com/my-app-updates/${process.platform}/${process.arch}`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Using update.electronjs.org
|
||||
|
||||
The Electron team maintains [update.electronjs.org][], a free and open-source
|
||||
|
@ -151,6 +259,10 @@ server-communication aspect of the process by loading your update from a local d
|
|||
|
||||
:::
|
||||
|
||||
## Update server specification
|
||||
|
||||
A Squirrel-compatible update server has different
|
||||
|
||||
[vercel]: https://vercel.com
|
||||
[hazel]: https://github.com/vercel/hazel
|
||||
[nuts]: https://github.com/GitbookIO/nuts
|
||||
|
|
Loading…
Reference in a new issue