Mac App Store
The top-level mas key contains set of options instructing electron-builder on how it should build MAS (Mac Application Store) target. Inherits all macOS options.
Use the mas-dev target (configured via the top-level masDev key) for local testing of MAS builds with a development provisioning profile.
MAS vs. Direct Distribution
| Aspect | MAS Distribution | Direct Distribution (DMG) |
|---|---|---|
| Certificate | Mac App Distribution | Developer ID Application |
| Notarization | Not required (Apple handles it) | Required (macOS 10.15+) |
| Sandboxing | Mandatory | Optional |
| Update mechanism | Mac App Store | electron-updater |
| Revenue | Apple takes 30% (15% for small dev program) | 100% to you |
| Discovery | App Store search and Browse | Your own marketing |
| Review | Apple review (1-7 days) | Instant |
| macOS version support | As Apple dictates | You control |
Prerequisites
Certificates
You need a Mac App Distribution certificate (for signing the app) and an Mac Installer Distribution certificate (for signing the PKG submitted to App Store Connect). Both are issued from your Apple Developer account.
For local testing with mas-dev, you use a Development provisioning profile and a standard developer certificate, not the distribution ones.
Provisioning Profile
MAS apps require a provisioning profile that:
- Lists the specific entitlements your app uses
- Is tied to your App ID and certificate
Create provisioning profiles at developer.apple.com.
mas:
provisioningProfile: build/MyApp_AppStore.provisionprofile
App Sandbox
All MAS apps must be sandboxed. Add to your entitlements (build/entitlements.mas.plist):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- Required for sandboxed MAS apps -->
<key>com.apple.security.app-sandbox</key>
<true/>
<!-- Allow JIT compilation -->
<key>com.apple.security.cs.allow-jit</key>
<true/>
<!-- Network access (if needed) -->
<key>com.apple.security.network.client</key>
<true/>
</dict>
</plist>
And build/entitlements.mas.inherit.plist for helper processes:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.inherit</key>
<true/>
</dict>
</plist>
Point to these in your configuration:
mas:
entitlements: build/entitlements.mas.plist
entitlementsInherit: build/entitlements.mas.inherit.plist
provisioningProfile: build/MyApp_AppStore.provisionprofile
Common MAS Entitlements
| Entitlement | Purpose |
|---|---|
com.apple.security.app-sandbox | Required for MAS |
com.apple.security.network.client | Outgoing network connections |
com.apple.security.network.server | Incoming connections |
com.apple.security.files.user-selected.read-write | Open/Save panels |
com.apple.security.files.downloads.read-write | Downloads folder access |
com.apple.security.device.camera | Camera |
com.apple.security.device.microphone | Microphone |
com.apple.security.personal-information.contacts | Contacts |
com.apple.security.personal-information.calendars | Calendar |
com.apple.security.print | Printing |
com.apple.security.automation.apple-events | AppleScript/Apple Events |
Testing with mas-dev
The mas-dev target produces a build signed with a development certificate and development provisioning profile — suitable for testing sandbox behavior on your machine without going through App Store review.
masDev:
provisioningProfile: build/MyApp_Dev.provisionprofile
entitlements: build/entitlements.mas.plist
entitlementsInherit: build/entitlements.mas.inherit.plist
Build the dev target:
electron-builder --mac mas-dev
Building for the App Store
electron-builder --mac mas
This produces:
MyApp-<version>.pkg— the package to upload to App Store Connect
Submitting to App Store Connect
- Open App Store Connect
- Create your app listing (if new) under My Apps → +
- Use Transporter (free, from the Mac App Store) or
xcrun altool/xcrun notarytoolto upload the.pkg - The uploaded build appears in App Store Connect after processing (usually a few minutes)
- Select the build for your release and submit for review
Common Review Rejection Reasons
- Sandbox violations — the app attempts to access files or resources not permitted by entitlements
- Deprecated APIs — using APIs Apple has removed or flagged (check release notes)
- Missing privacy strings — if you access camera/mic/location,
NSCameraUsageDescriptionetc. must be inInfo.plist - UI guidelines violations — buttons, windows, or flows that don't match Human Interface Guidelines
- Crash on launch — always test the MAS build on a clean machine before submitting
Configuration
Interface: MasConfiguration
Extends
Properties
additionalArguments?
readonlyoptionaladditionalArguments?:string[] |null
Array of strings specifying additional arguments to pass to the codesign command used to sign a specific file.
Some subresources that you may include in your Electron app may need to be signed with --deep, this is not typically safe to apply to the entire Electron app and therefore should be applied to just your file.
Usage Example: ['--deep']
Inherited from
MacConfiguration.additionalArguments
appId?
readonlyoptionalappId?:string|null
The application id. Used as CFBundleIdentifier for MacOS and as Application User Model ID for Windows (NSIS target only, Squirrel.Windows not supported). It is strongly recommended that an explicit ID is set.
Default
com.electron.${name}
Inherited from
artifactName?
readonlyoptionalartifactName?:string|null
The artifact file name template. Defaults to ${productName}-${version}.${ext} (some target can have other defaults, see corresponding options).
Inherited from
asar?
readonlyoptionalasar?:boolean|AsarOptions|null
Whether to package the application's source code into an archive, using Electron's archive format.
Node modules, that must be unpacked, will be detected automatically, you don't need to explicitly set asarUnpack - please file an issue if this doesn't work.
Default
true
Inherited from
asarUnpack?
readonlyoptionalasarUnpack?:string|string[] |null
A glob patterns relative to the app directory, which specifies which files to unpack when creating the asar archive.
Inherited from
binaries?
readonlyoptionalbinaries?:string[] |null
Paths of any extra binaries that need to be signed.
Overrides
bundleShortVersion?
readonlyoptionalbundleShortVersion?:string|null
The CFBundleShortVersionString. Do not use it unless you need to.
Inherited from
MacConfiguration.bundleShortVersion
bundleVersion?
readonlyoptionalbundleVersion?:string|null
The CFBundleVersion. Do not use it unless you need to.
Inherited from
MacConfiguration.bundleVersion
category?
readonlyoptionalcategory?:string|null
The application category type, as shown in the Finder via View -> Arrange by Application Category when viewing the Applications directory.
For example, "category": "public.app-category.developer-tools" will set the application category to Developer Tools.
Valid values are listed in Apple's documentation.
Inherited from
compression?
readonlyoptionalcompression?:CompressionLevel|null
The compression level. If you want to rapidly test build, store can reduce build time significantly. maximum doesn't lead to noticeable size difference, but increase build time.
Default
normal
Inherited from
darkModeSupport?
readonlyoptionaldarkModeSupport?:boolean
Whether a dark mode is supported. If your app does have a dark mode, you can make your app follow the system-wide dark mode setting.
Default
false
Inherited from
MacConfiguration.darkModeSupport
defaultArch?
readonlyoptionaldefaultArch?:string
The default architecture to build for when no --arch flag is specified.
Defaults to the current machine's architecture.
Inherited from
detectUpdateChannel?
readonlyoptionaldetectUpdateChannel?:boolean
Whether to infer update channel from application version pre-release components. e.g. if version 0.12.1-alpha.1, channel will be set to alpha. Otherwise to latest.
This does not apply to github publishing, which will never auto-detect the update channel.
Default
true
Inherited from
MacConfiguration.detectUpdateChannel
disableDefaultIgnoredFiles?
optionaldisableDefaultIgnoredFiles?:boolean|null
Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to false.
Default
false
Inherited from
MacConfiguration.disableDefaultIgnoredFiles
electronLanguages?
readonlyoptionalelectronLanguages?:string|string[]
The electron locales to keep. By default, all Electron locales used as-is.
Inherited from
MacConfiguration.electronLanguages
electronUpdaterCompatibility?
readonlyoptionalelectronUpdaterCompatibility?:string|null
The electron-updater compatibility semver range.
Inherited from
MacConfiguration.electronUpdaterCompatibility
entitlements?
readonlyoptionalentitlements?:string|null
The path to entitlements file for signing the app. build/entitlements.mas.plist will be used if exists (it is a recommended way to set).
See this folder in osx-sign's repository for examples.
Be aware that your app may crash if the right entitlements are not set like com.apple.security.cs.allow-jit for example on arm64 builds with Electron 20+.
See Signing and Notarizing macOS Builds from the Electron documentation for more information.
Overrides
entitlementsInherit?
readonlyoptionalentitlementsInherit?:string|null
The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. build/entitlements.mas.inherit.plist will be used if exists (it is a recommended way to set).
See this folder in osx-sign's repository for examples.
Overrides
MacConfiguration.entitlementsInherit
entitlementsLoginHelper?
readonlyoptionalentitlementsLoginHelper?:string|null
Path to login helper entitlement file.
When using App Sandbox, the the com.apple.security.inherit key that is normally in the inherited entitlements cannot be inherited since the login helper is a standalone executable.
Defaults to the value provided for entitlements. This option only applies when signing with entitlements provided.
Inherited from
MacConfiguration.entitlementsLoginHelper
executableName?
readonlyoptionalexecutableName?:string|null
The executable name. Defaults to productName
Note: Except for Linux, where this would constitute a breaking change in previous behavior and lead to both invalid executable names and Desktop files. Ref comments in: https://github.com/electron-userland/electron-builder/pull/9068
Inherited from
MacConfiguration.executableName
extendInfo?
readonlyoptionalextendInfo?:any
The extra entries for Info.plist.
Inherited from
extraDistFiles?
readonlyoptionalextraDistFiles?:string|string[] |null
Extra files to put in archive. Not applicable for tar.*.
Inherited from
MacConfiguration.extraDistFiles
extraFiles?
optionalextraFiles?:string|FileSet| (string|FileSet)[] |null
The same as extraResources but copy into the app's content directory (Contents for MacOS, root directory for Linux and Windows).
Inherited from
extraResources?
optionalextraResources?:string|FileSet| (string|FileSet)[] |null
A glob patterns relative to the project directory, when specified, copy the file or directory with matching names directly into the app's resources directory (Contents/Resources for MacOS, resources for Linux and Windows).
File patterns (and support for from and to fields) the same as for files.
Inherited from
MacConfiguration.extraResources
fileAssociations?
readonlyoptionalfileAssociations?:FileAssociation|FileAssociation[]
The file associations.
Inherited from
MacConfiguration.fileAssociations
files?
optionalfiles?:string|FileSet| (string|FileSet)[] |null
A glob patterns relative to the app directory, which specifies which files to include when copying files to create the package.
Defaults to:
[
"**/*",
"!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
"!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
"!**/node_modules/*.d.ts",
"!**/node_modules/.bin",
"!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}",
"!.editorconfig",
"!**/._*",
"!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}",
"!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}",
"!**/{appveyor.yml,.travis.yml,circle.yml}",
"!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}"
]
Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default.
Default pattern **/* is not added to your custom if some of your patterns is not ignore (i.e. not starts with !). package.json and **/node_modules/**/* (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns.
May be specified in the platform options (e.g. in the mac).
You may also specify custom source and destination directories by using FileSet objects instead of simple glob patterns.
[
{
"from": "path/to/source",
"to": "path/to/destination",
"filter": ["**/*", "!foo/*.js"]
}
]
You can use file macros in the from and to fields as well. from and to can be files and you can use this to rename a file while packaging.
Inherited from
forceCodeSigning?
readonlyoptionalforceCodeSigning?:boolean
Whether to fail if app will be not code signed.
Default
false
Inherited from
MacConfiguration.forceCodeSigning
gatekeeperAssess?
readonlyoptionalgatekeeperAssess?:boolean
Whether to let @electron/osx-sign validate the signing or not.
Default
false
Inherited from
MacConfiguration.gatekeeperAssess
generateUpdatesFilesForAllChannels?
readonlyoptionalgenerateUpdatesFilesForAllChannels?:boolean
Please see Building and Releasing using Channels.
Default
false
Inherited from
MacConfiguration.generateUpdatesFilesForAllChannels
hardenedRuntime?
readonlyoptionalhardenedRuntime?:boolean
Whether your app has to be signed with hardened runtime.
Default
true
Inherited from
MacConfiguration.hardenedRuntime
helperBundleId?
readonlyoptionalhelperBundleId?:string|null
The bundle identifier to use in the application helper's plist.
Default
${appBundleIdentifier}.helper
Inherited from
MacConfiguration.helperBundleId
helperEHBundleId?
readonlyoptionalhelperEHBundleId?:string|null
The bundle identifier to use in the EH helper's plist.
Default
${appBundleIdentifier}.helper.EH
Inherited from
MacConfiguration.helperEHBundleId
helperGPUBundleId?
readonlyoptionalhelperGPUBundleId?:string|null
The bundle identifier to use in the GPU helper's plist.
Default
${appBundleIdentifier}.helper.GPU
Inherited from
MacConfiguration.helperGPUBundleId
helperNPBundleId?
readonlyoptionalhelperNPBundleId?:string|null
The bundle identifier to use in the NP helper's plist.
Default
${appBundleIdentifier}.helper.NP
Inherited from
MacConfiguration.helperNPBundleId
helperPluginBundleId?
readonlyoptionalhelperPluginBundleId?:string|null
The bundle identifier to use in the Plugin helper's plist.
Default
${appBundleIdentifier}.helper.Plugin
Inherited from
MacConfiguration.helperPluginBundleId
helperRendererBundleId?
readonlyoptionalhelperRendererBundleId?:string|null
The bundle identifier to use in the Renderer helper's plist.
Default
${appBundleIdentifier}.helper.Renderer
Inherited from
MacConfiguration.helperRendererBundleId
icon?
readonlyoptionalicon?:string|null
The path to application icon.
Accepts .icns (legacy) or .icon (Icon Composer asset).
If a .icon asset is provided, it will be preferred and compiled to an asset catalog.
Default
build/icon.icns
Inherited from
identity?
readonlyoptionalidentity?:string|null
The name of certificate to use when signing. Consider using environment variables CSC_LINK or CSC_NAME instead of specifying this option. MAS installer identity is specified in the mas.
Set to - to use an ad-hoc identity for signing. Set to null to skip signing entirely.
Inherited from
mergeASARs?
readonlyoptionalmergeASARs?:boolean
Whether to merge ASAR files for different architectures or not.
This option has no effect unless building for "universal" arch.
Default
true
Inherited from
minimumSystemVersion?
readonlyoptionalminimumSystemVersion?:string|null
The minimum version of macOS required for the app to run. Corresponds to LSMinimumSystemVersion.
Inherited from
MacConfiguration.minimumSystemVersion
notarize?
readonlyoptionalnotarize?:boolean
Whether to disable electron-builder's @electron/notarize integration.
Note: In order to activate the notarization step You MUST specify one of the following via environment variables:
APPLE_API_KEY,APPLE_API_KEY_IDandAPPLE_API_ISSUER.APPLE_ID,APPLE_APP_SPECIFIC_PASSWORD, andAPPLE_TEAM_IDAPPLE_KEYCHAINandAPPLE_KEYCHAIN_PROFILE
For security reasons it is recommended to use the first option (see https://github.com/electron-userland/electron-builder/issues/7859)
Inherited from
preAutoEntitlements?
readonlyoptionalpreAutoEntitlements?:boolean
Whether to enable entitlements automation from @electron/osx-sign.
Default
true
Inherited from
MacConfiguration.preAutoEntitlements
protocols?
The URL protocol schemes.
Inherited from
provisioningProfile?
readonlyoptionalprovisioningProfile?:string|null
The path to the provisioning profile to use when signing, absolute or relative to the app root.
Inherited from
MacConfiguration.provisioningProfile
publish?
optionalpublish?:Publish
Publisher configuration. See Auto Update for more information.
Inherited from
releaseInfo?
readonlyoptionalreleaseInfo?:ReleaseInfo
The release info. Intended for command line usage:
-c.releaseInfo.releaseNotes="new features"
Inherited from
requirements?
readonlyoptionalrequirements?:string|null
Path of requirements file used in signing. Not applicable for MAS.
Inherited from
sign?
readonlyoptionalsign?:string|CustomMacSign|null
The custom function (or path to file or module id) to sign an app bundle.
Inherited from
signIgnore?
readonlyoptionalsignIgnore?:string|string[] |null
Regex or an array of regex's that signal skipping signing a file.
Inherited from
singleArchFiles?
readonlyoptionalsingleArchFiles?:string|null
Minimatch pattern of paths that are allowed to be present in one of the ASAR files, but not in the other.
This option has no effect unless building for "universal" arch and applies
only if mergeASARs is true.
Inherited from
MacConfiguration.singleArchFiles
strictVerify?
readonlyoptionalstrictVerify?:boolean
Whether to let @electron/osx-sign verify the contents or not.
Default
true
Inherited from
target?
readonlyoptionaltarget?:TargetConfiguration|MacOsTargetName| TargetConfiguration | MacOsTargetName[] |null
The target package type: list of default, dmg, mas, mas-dev, pkg, 7z, zip, tar.xz, tar.lz, tar.gz, tar.bz2, dir.
Note: Squirrel.Mac auto update mechanism requires both dmg and zip to be enabled, even when only dmg is used. Disabling zip will break auto update in dmg packages.
Default
default (dmg and zip for Squirrel.Mac)
Inherited from
timestamp?
readonlyoptionaltimestamp?:string|null
Specify the URL of the timestamp authority server
Inherited from
type?
readonlyoptionaltype?:"distribution"|"development"|null
Whether to sign app for development or for distribution.
Default
distribution
Inherited from
x64ArchFiles?
readonlyoptionalx64ArchFiles?:string|null
Minimatch pattern of paths that are allowed to be x64 binaries in both ASAR files
This option has no effect unless building for "universal" arch and applies
only if mergeASARs is true.