diff --git a/docs/tutorial/code-signing.md b/docs/tutorial/code-signing.md index 06fae1eaf7..0bb18aaf56 100644 --- a/docs/tutorial/code-signing.md +++ b/docs/tutorial/code-signing.md @@ -52,15 +52,17 @@ ways to get your application signed and notarized. If you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a collection of the official Electron tools, using [`electron-packager`], -[`electron-osx-sign`], and [`electron-notarize`] under the hood. +[`@electron/osx-sign`], and [`@electron/notarize`] under the hood. -Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos). +Detailed instructions on how to configure your application can be found in the +[Signing macOS Apps](https://www.electronforge.io/guides/code-signing/code-signing-macos) guide in +the Electron Forge docs. ### Using Electron Packager If you're not using an integrated build pipeline like Forge, you -are likely using [`electron-packager`], which includes [`electron-osx-sign`] and -[`electron-notarize`]. +are likely using [`electron-packager`], which includes [`@electron/osx-sign`] and +[`@electron/notarize`]. If you're using Packager's API, you can pass [in configuration that both signs and notarizes your application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html). @@ -70,13 +72,7 @@ const packager = require('electron-packager') packager({ dir: '/path/to/my/app', - osxSign: { - identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)', - 'hardened-runtime': true, - entitlements: 'entitlements.plist', - 'entitlements-inherit': 'entitlements.plist', - 'signature-flags': 'library' - }, + osxSign: {}, osxNotarize: { appleId: 'felix@felix.fun', appleIdPassword: 'my-apple-id-password' @@ -84,26 +80,6 @@ packager({ }) ``` -The `entitlements.plist` file referenced here needs the following macOS-specific entitlements -to assure the Apple security mechanisms that your app is doing these things -without meaning any harm: - -```xml title="entitlements.plist" - - - - - com.apple.security.cs.allow-jit - - com.apple.security.cs.debugger - - - -``` - -Up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required -as well. However, it should not be used anymore if it can be avoided. - ### Signing Mac App Store applications See the [Mac App Store Guide]. @@ -213,15 +189,14 @@ can find [its documentation here](https://www.electron.build/code-signing). See the [Windows Store Guide]. [apple developer program]: https://developer.apple.com/programs/ -[`electron-builder`]: https://github.com/electron-userland/electron-builder -[`electron-forge`]: https://github.com/electron-userland/electron-forge -[`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign +[`electron-forge`]: https://github.com/electron/forge +[`@electron/osx-sign`]: https://github.com/electron/osx-sign [`electron-packager`]: https://github.com/electron/electron-packager -[`electron-notarize`]: https://github.com/electron/electron-notarize +[`@electron/notarize`]: https://github.com/electron/notarize [`electron-winstaller`]: https://github.com/electron/windows-installer -[`electron-wix-msi`]: https://github.com/felixrieseberg/electron-wix-msi +[`electron-wix-msi`]: https://github.com/electron-userland/electron-wix-msi [xcode]: https://developer.apple.com/xcode -[signing certificates]: https://github.com/electron/electron-osx-sign/wiki/1.-Getting-Started#certificates +[signing certificates]: https://developer.apple.com/support/certificates/ [mac app store guide]: ./mac-app-store-submission-guide.md [windows store guide]: ./windows-store-guide.md [maker-squirrel]: https://www.electronforge.io/config/makers/squirrel.windows diff --git a/docs/tutorial/mac-app-store-submission-guide.md b/docs/tutorial/mac-app-store-submission-guide.md index 79b087dd98..004f204c9e 100644 --- a/docs/tutorial/mac-app-store-submission-guide.md +++ b/docs/tutorial/mac-app-store-submission-guide.md @@ -11,7 +11,7 @@ This guide provides information on: To sign Electron apps, the following tools must be installed first: * Xcode 11 or above. -* The [electron-osx-sign][electron-osx-sign] npm module. +* The [@electron/osx-sign] npm module. You also have to register an Apple Developer account and join the [Apple Developer Program][developer-program]. @@ -103,7 +103,7 @@ Apps submitted to the Mac App Store must run under Apple's the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox. -When signing the app with `electron-osx-sign`, it will automatically add the +When signing the app with `@electron/osx-sign`, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added: @@ -120,7 +120,7 @@ entitlements, you must ensure App Sandbox capacity is added: #### Extra steps without `electron-osx-sign` -If you are signing your app without using `electron-osx-sign`, you must ensure +If you are signing your app without using `@electron/osx-sign`, you must ensure the app bundle's entitlements have at least following keys: ```xml @@ -170,22 +170,22 @@ your Apple Developer account's Team ID as its value: ``` -When using `electron-osx-sign` the `ElectronTeamID` key will be added +When using `@electron/osx-sign` the `ElectronTeamID` key will be added automatically by extracting the Team ID from the certificate's name. You may -need to manually add this key if `electron-osx-sign` could not find the correct +need to manually add this key if `@electron/osx-sign` could not find the correct Team ID. ### Sign apps for development To sign an app that can run on your development machine, you must sign it with the "Apple Development" certificate and pass the provisioning profile to -`electron-osx-sign`. +`@electron/osx-sign`. ```bash electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile ``` -If you are signing without `electron-osx-sign`, you must place the provisioning +If you are signing without `@electron/osx-sign`, you must place the provisioning profile to `YourApp.app/Contents/embedded.provisionprofile`. The signed app can only run on the machines that registered by the provisioning @@ -213,7 +213,7 @@ use App Sandbox. electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess ``` -By passing `--no-gatekeeper-assess`, the `electron-osx-sign` will skip the macOS +By passing `--no-gatekeeper-assess`, `@electron/osx-sign` will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step. @@ -341,7 +341,7 @@ Electron uses following cryptographic algorithms: * RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004) [developer-program]: https://developer.apple.com/support/compare-memberships/ -[electron-osx-sign]: https://github.com/electron/electron-osx-sign +[@electron/osx-sign]: https://github.com/electron/electron-osx-sign [app-sandboxing]: https://developer.apple.com/app-sandboxing/ [app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution [submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html diff --git a/docs/tutorial/tutorial-1-prerequisites.md b/docs/tutorial/tutorial-1-prerequisites.md index 164811fc4e..c3bfd8f864 100644 --- a/docs/tutorial/tutorial-1-prerequisites.md +++ b/docs/tutorial/tutorial-1-prerequisites.md @@ -26,6 +26,15 @@ work on Windows, macOS, and Linux with a single JavaScript codebase. This tutorial will guide you through the process of developing a desktop application with Electron and distributing it to end users. +## Goals + +This tutorial starts by guiding you through the process of piecing together +a minimal Electron application from scratch, then teaches you how to +package and distribute it to users using Electron Forge. + +If you prefer to get a project started with a single-command boilerplate, we recommend you start +with Electron Forge's [`create-electron-app`](https://www.electronforge.io/) command. + ## Assumptions Electron is a native wrapper layer for web apps and is run in a Node.js environment. diff --git a/docs/tutorial/tutorial-5-packaging.md b/docs/tutorial/tutorial-5-packaging.md index 032511145e..d803035675 100644 --- a/docs/tutorial/tutorial-5-packaging.md +++ b/docs/tutorial/tutorial-5-packaging.md @@ -70,10 +70,9 @@ the [Electron Forge CLI documentation]. ::: You should also notice that your package.json now has a few more packages installed -under your `devDependencies`, and contains an added `config.forge` field with an array -of makers configured. **Makers** are Forge plugins that create distributables from -your source code. You should see multiple makers in the pre-populated configuration, -one for each target platform. +under `devDependencies`, and a new `forge.config.js` file that exports a configuration +object. You should see multiple makers (packages that generate distributable app bundles) in the +pre-populated configuration, one for each target platform. ### Creating a distributable @@ -111,13 +110,14 @@ Electron Forge can be configured to create distributables in different OS-specif ::: -:::tip Creating and Adding Application Icons +:::tip Creating and adding application icons -Setting custom application icons requires a few additions to your config. Check out [Forge's icon tutorial] for more information. +Setting custom application icons requires a few additions to your config. +Check out [Forge's icon tutorial] for more information. ::: -:::note Packaging without Electron Forge +:::info Packaging without Electron Forge If you want to manually package your code, or if you're just interested understanding the mechanics behind packaging an Electron app, check out the full [Application Packaging] @@ -136,64 +136,51 @@ Code signing is a security technology that you use to certify that a desktop app created by a known source. Windows and macOS have their own OS-specific code signing systems that will make it difficult for users to download or launch unsigned applications. -If you already have code signing certificates for Windows and macOS, you can set your -credentials in your Forge configuration. Otherwise, please refer to the full -[Code Signing] documentation to learn how to purchase a certificate and for more information -on the desktop app code signing process. - On macOS, code signing is done at the app packaging level. On Windows, distributable installers -are signed instead. +are signed instead. If you already have code signing certificates for Windows and macOS, you can set +your credentials in your Forge configuration. + +:::info + +For more information on code signing, check out the +[Signing macOS Apps](https://www.electronforge.io/guides/code-signing) guide in the Forge docs. + +::: -```json title='package.json' {6-18} -{ - //... - "config": { - "forge": { - //... - "packagerConfig": { - "osxSign": { - "identity": "Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)", - "hardened-runtime": true, - "entitlements": "entitlements.plist", - "entitlements-inherit": "entitlements.plist", - "signature-flags": "library" - }, - "osxNotarize": { - "appleId": "felix@felix.fun", - "appleIdPassword": "this-is-a-secret" - } - } - //... +```js title='forge.config.js' +module.exports = { + packagerConfig: { + osxSign: {}, + //... + osxNotarize: { + tool: 'notarytool', + appleId: process.env.APPLE_ID, + appleIdPassword: process.env.APPLE_PASSWORD, + teamId: process.env.APPLE_TEAM_ID, } + //... } - //... } ``` -```json title='package.json' {6-14} -{ +```js title='forge.config.js' +module.exports = { //... - "config": { - "forge": { - //... - "makers": [ - { - "name": "@electron-forge/maker-squirrel", - "config": { - "certificateFile": "./cert.pfx", - "certificatePassword": "this-is-a-secret" - } - } - ] - //... - } - } + makers: [ + { + name: '@electron-forge/maker-squirrel', + config: { + certificateFile: './cert.pfx', + certificatePassword: process.env.CERTIFICATE_PASSWORD, + }, + }, + ], //... } ``` @@ -214,13 +201,12 @@ information. [`@electron/osx-sign`]: https://github.com/electron/osx-sign [application packaging]: ./application-distribution.md -[code signing]: ./code-signing.md [`electron-packager`]: https://github.com/electron/electron-packager [`electron-winstaller`]: https://github.com/electron/windows-installer [electron forge]: https://www.electronforge.io [electron forge cli documentation]: https://www.electronforge.io/cli#commands [makers]: https://www.electronforge.io/config/makers -[Forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons +[forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons diff --git a/docs/tutorial/tutorial-6-publishing-updating.md b/docs/tutorial/tutorial-6-publishing-updating.md index dc0fdc31f2..4adfb434bd 100644 --- a/docs/tutorial/tutorial-6-publishing-updating.md +++ b/docs/tutorial/tutorial-6-publishing-updating.md @@ -78,27 +78,21 @@ 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 - } - } - ] - } - } - //... +```js title='forge.config.js' +module.exports = { + publishers: [ + { + name: '@electron-forge/publisher-github', + config: { + repository: { + owner: 'github-user-name', + name: 'github-repo-name', + }, + prerelease: false, + draft: true, + }, + }, + ], } ```