diff --git a/docs/tutorial/updates.md b/docs/tutorial/updates.md index 44bd64dea211..4edf4a6efbab 100644 --- a/docs/tutorial/updates.md +++ b/docs/tutorial/updates.md @@ -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. + +
+Manual publishing + +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 +``` + +
+ +### 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