docs: expand tutorial (#34604)
* docs: base tutorial update * more docs * zzz * remove unused images
This commit is contained in:
Erick Zhao
GitHub
parent
a5869fe997
commit
e410109a3d
23 changed files with 2009 additions and 202 deletions
251
docs/tutorial/tutorial-6-publishing-updating.md
Normal file
251
docs/tutorial/tutorial-6-publishing-updating.md
Normal file
|
|
@ -0,0 +1,251 @@
|
|||
---
|
||||
title: 'Publishing and Updating'
|
||||
description: "There are several ways to update an Electron application. The easiest and officially supported one is taking advantage of the built-in Squirrel framework and Electron's autoUpdater module."
|
||||
slug: tutorial-publishing-updating
|
||||
hide_title: false
|
||||
---
|
||||
|
||||
:::info Follow along the tutorial
|
||||
|
||||
This is **part 6** of the Electron tutorial.
|
||||
|
||||
1. [Prerequisites][prerequisites]
|
||||
1. [Building your First App][building your first app]
|
||||
1. [Using Preload Scripts][preload]
|
||||
1. [Adding Features][features]
|
||||
1. [Packaging Your Application][packaging]
|
||||
1. **[Publishing and Updating][updates]**
|
||||
|
||||
:::
|
||||
|
||||
## Learning goals
|
||||
|
||||
If you've been following along, this is the last step of the tutorial! In this part,
|
||||
you will publish your app to GitHub releases and integrate automatic updates
|
||||
into your app code.
|
||||
|
||||
## Using update.electronjs.org
|
||||
|
||||
The Electron maintainers provide a free auto-updating service for open-source apps
|
||||
at https://update.electronjs.org. Its requirements are:
|
||||
|
||||
- Your app runs on macOS or Windows
|
||||
- Your app has a public GitHub repository
|
||||
- Builds are published to [GitHub releases]
|
||||
- Builds are [code signed][code-signed]
|
||||
|
||||
At this point, we'll assume that you have already pushed all your
|
||||
code to a public GitHub repository.
|
||||
|
||||
:::info Alternative update services
|
||||
|
||||
If you're using an alternate repository host (e.g. GitLab or Bitbucket) or if
|
||||
you need to keep your code repository private, please refer to our
|
||||
[step-by-step guide][update-server] on hosting your own Electron update server.
|
||||
|
||||
:::
|
||||
|
||||
## Publishing a GitHub release
|
||||
|
||||
Electron Forge has [Publisher] plugins that can automate the distribution
|
||||
of your packaged application to various sources. In this tutorial, we will
|
||||
be using the GitHub Publisher, which will allow us to publish
|
||||
our code to GitHub releases.
|
||||
|
||||
### Generating a personal access token
|
||||
|
||||
Forge cannot publish to any repository on GitHub without permission. You
|
||||
need to pass in an authenticated token that gives Forge access to
|
||||
your GitHub releases. The easiest way to do this is to
|
||||
[create a new personal access token (PAT)][new-pat]
|
||||
with the `public_repo` scope, which gives write access to your public repositories.
|
||||
**Make sure to keep this token a secret.**
|
||||
|
||||
### Setting up the GitHub Publisher
|
||||
|
||||
#### Installing the module
|
||||
|
||||
Forge's [GitHub Publisher] is a plugin that
|
||||
needs to be installed in your project's `devDependencies`:
|
||||
|
||||
```sh npm2yarn
|
||||
npm install --save-dev @electron-forge/publisher-github
|
||||
```
|
||||
|
||||
#### Configuring the publisher in Forge
|
||||
|
||||
Once you have it installed, you need to set it up in your Forge
|
||||
configuration. A full list of options is documented in the Forge's
|
||||
[`PublisherGitHubConfig`] API docs.
|
||||
|
||||
```json title='package.json' {6-16}
|
||||
{
|
||||
//...
|
||||
"config": {
|
||||
"forge": {
|
||||
"publishers": [
|
||||
{
|
||||
"name": "@electron-forge/publisher-github",
|
||||
"config": {
|
||||
"repository": {
|
||||
"owner": "github-user-name",
|
||||
"name": "github-repo-name"
|
||||
},
|
||||
"prerelease": false,
|
||||
"draft": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
//...
|
||||
}
|
||||
```
|
||||
|
||||
:::tip Drafting releases before publishing
|
||||
|
||||
Notice that you have configured Forge to publish your release as a draft.
|
||||
This will allow you to see the release with its generated artifacts
|
||||
without actually publishing it to your end users. You can manually
|
||||
publish your releases via GitHub after writing release notes and
|
||||
double-checking that your distributables work.
|
||||
|
||||
:::
|
||||
|
||||
#### Setting up your authentication token
|
||||
|
||||
You also need to make the Publisher aware of your authentication token.
|
||||
By default, it will use the value stored in the `GITHUB_TOKEN` environment
|
||||
variable.
|
||||
|
||||
### Running the publish command
|
||||
|
||||
Add Forge's [publish command] to your npm scripts.
|
||||
|
||||
```json {6} title='package.json'
|
||||
//...
|
||||
"scripts": {
|
||||
"start": "electron-forge start",
|
||||
"package": "electron-forge package",
|
||||
"make": "electron-forge make",
|
||||
"publish": "electron-forge publish"
|
||||
},
|
||||
//...
|
||||
```
|
||||
|
||||
This command will run your configured makers and publish the output distributables to a new
|
||||
GitHub release.
|
||||
|
||||
```sh npm2yarn
|
||||
npm run publish
|
||||
```
|
||||
|
||||
By default, this will only publish a single distributable for your host operating system and
|
||||
architecture. You can publish for different architectures by passing in the `--arch` flag to your
|
||||
Forge commands.
|
||||
|
||||
The name of this release will correspond to the `version` field in your project's package.json file.
|
||||
|
||||
:::tip Tagging releases
|
||||
|
||||
Optionally, you can also [tag your releases in Git][git-tag] so that your
|
||||
release is associated with a labeled point in your code history. npm comes
|
||||
with a handy [`npm version`](https://docs.npmjs.com/cli/v8/commands/npm-version)
|
||||
command that can handle the version bumping and tagging for you.
|
||||
|
||||
:::
|
||||
|
||||
#### Bonus: Publishing in GitHub Actions
|
||||
|
||||
Publishing locally can be painful, especially because you can only create distributables
|
||||
for your host operating system (i.e. you can't publish a Window `.exe` file from macOS).
|
||||
|
||||
A solution for this would be to publish your app via automation workflows
|
||||
such as [GitHub Actions], which can run tasks in the
|
||||
cloud on Ubuntu, macOS, and Windows. This is the exact approach taken by [Electron Fiddle].
|
||||
You can refer to Fiddle's [Build and Release pipeline][fiddle-build]
|
||||
and [Forge configuration][fiddle-forge-config]
|
||||
for more details.
|
||||
|
||||
## Instrumenting your updater code
|
||||
|
||||
Now that we have a functional release system via GitHub releases, we now need to tell our
|
||||
Electron app to download an update whenever a new release is out. Electron apps do this
|
||||
via the [autoUpdater] module, which reads from an update server feed to check if a new version
|
||||
is available for download.
|
||||
|
||||
The update.electronjs.org service provides an updater-compatible feed. For example, Electron
|
||||
Fiddle v0.28.0 will check the endpoint at https://update.electronjs.org/electron/fiddle/darwin/v0.28.0
|
||||
to see if a newer GitHub release is available.
|
||||
|
||||
After your release is published to GitHub, the update.electronjs.org service should work
|
||||
for your application. The only step left is to configure the feed with the autoUpdater module.
|
||||
|
||||
To make this process easier, the Electron team maintains the [`update-electron-app`] module,
|
||||
which sets up the autoUpdater boilerplate for update.electronjs.org in one function
|
||||
call — no configuration required. This module will search for the update.electronjs.org
|
||||
feed that matches your project's package.json `"repository"` field.
|
||||
|
||||
First, install the module as a runtime dependency.
|
||||
|
||||
```sh npm2yarn
|
||||
npm install update-electron-app
|
||||
```
|
||||
|
||||
Then, import the module and call it immediately in the main process.
|
||||
|
||||
```js title='main.js'
|
||||
require('update-electron-app')()
|
||||
```
|
||||
|
||||
And that is all it takes! Once your application is packaged, it will update itself for each new
|
||||
GitHub release that you publish.
|
||||
|
||||
## Summary
|
||||
|
||||
In this tutorial, we configured Electron Forge's GitHub Publisher to upload your app's
|
||||
distributables to GitHub releases. Since distributables cannot always be generated
|
||||
between platforms, we recommend setting up your building and publishing flow
|
||||
in a Continuous Integration pipeline if you do not have access to machines.
|
||||
|
||||
Electron applications can self-update by pointing the autoUpdater module to an update server feed.
|
||||
update.electronjs.org is a free update server provided by Electron for open-source applications
|
||||
published on GitHub releases. Configuring your Electron app to use this service is as easy as
|
||||
installing and importing the `update-electron-app` module.
|
||||
|
||||
If your application is not eligible for update.electronjs.org, you should instead deploy your
|
||||
own update server and configure the autoUpdater module yourself.
|
||||
|
||||
:::info 🌟 You're done!
|
||||
|
||||
From here, you have officially completed our tutorial to Electron. Feel free to explore the
|
||||
rest of our docs and happy developing! If you have questions, please stop by our community
|
||||
[Discord server].
|
||||
|
||||
:::
|
||||
|
||||
[autoupdater]: ../api/auto-updater.md
|
||||
[code-signed]: ./code-signing.md
|
||||
[discord server]: https://discord.com/invite/APGC3k5yaH
|
||||
[electron fiddle]: https://electronjs.org/fiddle
|
||||
[fiddle-build]: https://github.com/electron/fiddle/blob/master/.github/workflows/build.yaml
|
||||
[fiddle-forge-config]: https://github.com/electron/fiddle/blob/master/forge.config.js
|
||||
[github actions]: https://github.com/features/actions
|
||||
[github publisher]: https://www.electronforge.io/config/publishers/github
|
||||
[github releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository
|
||||
[git tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
|
||||
[new-pat]: https://github.com/settings/tokens/new
|
||||
[publish command]: https://www.electronforge.io/cli#publish
|
||||
[publisher]: https://www.electronforge.io/config/publishers
|
||||
[`publishergithubconfig`]: https://js.electronforge.io/publisher/github/interfaces/publishergithubconfig
|
||||
[`update-electron-app`]: https://github.com/electron/update-electron-app
|
||||
[update-server]: ./updates.md
|
||||
|
||||
<!-- Tutorial links -->
|
||||
|
||||
[prerequisites]: tutorial-1-prerequisites.md
|
||||
[building your first app]: tutorial-2-first-app.md
|
||||
[preload]: tutorial-3-preload.md
|
||||
[features]: tutorial-4-adding-features.md
|
||||
[packaging]: tutorial-5-packaging.md
|
||||
[updates]: tutorial-6-publishing-updating.md
|
||||
Loading…
Add table
Add a link
Reference in a new issue