Skip to content

1. Getting Started

Erick Zhao edited this page Jul 31, 2020 · 11 revisions

Distributing an Electron-based application on OS X has been made as simple as possible using the three tools:

electron-packager greatly streamlines the process because it downloads the necessary Electron build instead of having to obtain and override your system-installed version, and packs your web application automatically for either of the OS X distributions.

Note: As electron-osx-sign is now integrated in electron-packager, replacing the original codesign execution, it's unnecessary to have electron-osx-sign separately installed. However, installing it globally could give your build more customization.

Prerequisites

  • You must be a registered member of the Apple Developer Program. Please note that you could be charged by Apple in order to get issued with the required certificates.
  • You must have Xcode installed either from Mac App Store or from Apple Developer. It is not recommended to download your copy from other 3rd party sources for security reasons.
  • You must have Xcode Command Line Tools installed. To check whether it is available, try xcode-select --install and follow the instructions.
  • You must create a Mac App on iTunes Connect. For this walk-through we will use the name "My App" as the application name.
  • You must give your app a unique Bundle ID. For this walk-through, we will use the Bundle ID "com.mysite.myapp"
  • You must give your app a Version Number. For this walk-through, we will use the Version Number "1.0.0"
  • It is recommended to have an icon file somewhere in your source path to replace the default by Electron. For this walk-through we will use "Icon.icns". The Apple utility iconutil can be used to create the icon files for OS X applications.

Note: We assume npm is already installed on your local machine if you're packing your application in a different environment from development.

Certificates

In order to distribute your application either inside or outside the Mac App Store, you will have to have the following certificates from Apple after becoming a registered developer.

For distribution inside the Mac App Store:

  • Mac App Distribution: 3rd Party Mac Developer Application: * (*)
  • Mac Installer Distribution: 3rd Party Mac Developer Installer: * (*)

For distribution outside the Mac App Store:

  • Developer ID Application: Developer ID Application: * (*)
  • Developer ID Installer: Developer ID Installer: * (*)

Note: They appear to come in pairs. It is preferred to have every one of them installed so not to care about which is not yet installed for future works. However, if you may only want to distribute outside the Mac App Store, there is no need to have the 3rd Party Mac Developer ones installed; vice versa.

Create your Certificates

EITHER from Member Center at Apple Developer:

In Certificates, Identifiers & Profiles you may find under Mac Apps the Certificates, in which request could be made for Mac App Store and Developer ID production certificates.

For distribution inside the Mac App Store, you will need the following:

  • The first is a Production > Mac App Store > Mac App Distribution certificate.
  • The second is a Production > Mac App Store > Mac Installer Distribution certificate.

For distribution outside the Mac App Store, you will need the following:

  • The first is a Production > Developer ID > Developer ID Application certificate.
  • The second is a Production > Developer ID > Developer ID Installer certificate.

After you create the necessary certifications, download them and open each so that they are installed in your keychain.

Note: It's recommended to install them in login.keychain so electron-osx-sign and electron-osx-flat could recognize them automatically for ease of looking them up.

OR in Xcode:

Under Xcode > Preferences (⌘,) > Accounts, you may add your Apple ID. With your team selected, the View Details... in the bottom right could find you the available certificates for generation/download.

Install The Tools

We will be installing these tools globally (-g). You may install them locally for your project however if you do you may need to adjust paths.

# Install the latest of electron-packager
npm install electron-packager -g

# Install electron-osx-sign for more customization
npm install electron-osx-sign -g

Note: If the installation fails with disk permissions as it being globally, please re-try these commands again with superuser, with sudo su and your account password. This procedure may fail if your account isn't previously assigned with a password. To do so, you may navigate to System Preferences > Users & Groups and set up a password for your account.

Distribution

Inside the Mac App Store
# EITHER pack your app and sign it both at once
electron-packager . "My App" --platform=mas --arch=x64 --version=0.35.6 --app-bundle-id="com.mysite.myapp" --app-version="1.0.0" --build-version="1.0.100" --osx-sign

# OR pack your app first then manually sign it
electron-packager . "My App" --platform=mas --arch=x64 --version=0.35.6 --app-bundle-id="com.mysite.myapp" --app-version="1.0.0" --build-version="1.0.100"
# Code-sign app bundle
electron-osx-sign "My App-mas-x64/My App.app"

# Create installer package for shipping
electron-osx-flat "My App-mas-x64/My App.app"

Notice that the platform we use here is mas to indicate this build is for Mac App Store, in which certain libraries and private API calls are removed to avoid rejection from app review. If you have only one set of production certifications from iTunes Connect, then you can sign your app without specifying a signing identity, and allow electron-osx-sign to automatically detect your available certificate.

Outside the Mac App Store
# EITHER pack your app and sign it both at once
electron-packager . "My App" --platform=darwin --arch=x64 --version=0.35.6 --app-bundle-id="com.mysite.myapp" --app-version="1.0.0" --build-version="1.0.100" --osx-sign

# OR pack your app first then manually sign it
electron-packager . "My App" --platform=darwin --arch=x64 --version=0.35.6 --app-bundle-id="com.mysite.myapp" --app-version="1.0.0" --build-version="1.0.100"
# Code-sign app bundle
electron-osx-sign "My App-darwin-x64/My App.app"

# OPTIONAL: Create installer package for shipping
electron-osx-flat "My App-darwin-x64/My App.app"

Notice that the platform we use here is darwin to indicate this build is for OS X (not Mac App Store). If you have only one set of production certifications from iTunes Connect, then you can sign your app without specifying a signing identity, and allow electron-osx-sign to automatically detect your available certificate.