appx

The top-level appx key contains set of options instructing electron-builder on how it should build AppX packages for the Windows Store or enterprise sideloading.

All options are optional. All required AppX configuration is inferred and computed automatically.

When to Use AppX

AppX is the packaging format for the Microsoft Store (also called MSIX). Choose AppX when:

• Windows Store distribution — your app will be listed in the Microsoft Store
• Enterprise sideloading — IT manages app distribution via MDM/Intune without the Store
• Windows 10S / Windows SE — these locked-down Windows editions only run Store apps

For standard consumer distribution, NSIS is simpler. For enterprise deployment without the Store, MSI is often preferred.

AppX vs. NSIS vs. MSI

Aspect	AppX	NSIS	MSI
Windows Store	Yes	No	No
Sideloading	Yes (signed)	N/A	N/A
Enterprise MDM	Limited	No	Yes
Sandboxed	Partial	No	No
Auto-update	Store only (not electron-updater)	electron-updater	Not supported via electron-updater
Code signing	Required (or Store)	Recommended	Recommended

Code Signing

• Store distribution — no manual signing needed. The Windows Store signs the package with a Microsoft certificate during the submission process.
• Sideloading / enterprise — the AppX must be signed with a trusted certificate. See Windows Code Signing.

For self-signed certificates during development, see Microsoft's self-signed certificate guide.

AppX Assets

AppX requires specific logo/icon assets. Place them in the appx folder inside your build resources directory (default: build/appx/):

Asset	File Name	Required	Size
Store Logo	StoreLogo.png	Yes	50×50
Square 150×150	Square150x150Logo.png	Yes	150×150
Square 44×44	Square44x44Logo.png	Yes	44×44
Wide 310×150	Wide310x150Logo.png	Yes	310×150
Badge Logo	BadgeLogo.png	Optional	24×24
Large Tile	LargeTile.png	Optional	310×310
Small Tile	SmallTile.png	Optional	71×71
Splash Screen	SplashScreen.png	Optional	620×300

Default assets are used for the required logos if you don't provide your own. Scale variants (e.g., Square44x44Logo.scale-200.png) are supported — see Microsoft's tile asset guidelines.

Identity and Publisher

appx:
  applicationId: "MyApp"                       # must be alphanumeric, no spaces
  identityName: "MyCompany.MyApp"              # unique within the Store
  publisher: "CN=My Company, O=My Company, C=US"  # must match certificate Subject
  publisherDisplayName: "My Company"
  displayName: "My Application"               # displayed in Start menu

Publisher Must Match Certificate

The publisher value must exactly match the Subject field of your code signing certificate. Mismatches cause installation failures.

Capabilities

AppX apps declare the system capabilities they use. Specify capabilities in appx.capabilities:

appx:
  capabilities:
    - runFullTrust                  # default — allows unrestricted execution
    - internetClient               # outbound internet access
    - privateNetworkClientServer   # local network
    - webcam                       # camera access
    - microphone                   # microphone access

runFullTrust is required for most Electron apps (included by default). The full list of capabilities is in Microsoft's documentation.

Tile Customization

appx:
  backgroundColor: "#2c2c2c"    # tile background color (CSS color)
  showNameOnTiles: false        # show app name on tile (default: false)

Language Support

appx:
  languages:
    - en-US
    - de-DE
    - fr-FR
    - ja-JP

Declare which languages your app supports. This affects Store listings and localized resources.

Version Targeting

appx:
  minVersion: "10.0.17763.0"       # Windows 10 1809 minimum
  maxVersionTested: "10.0.22621.0" # Windows 11 22H2 tested maximum

Auto-Launch Extension

appx:
  addAutoLaunchExtension: false    # Default: false

When true, adds a startup task extension that runs the app on user login. Requires the runFullTrust capability.

Custom Manifest

For advanced scenarios, provide a completely custom AppX manifest:

appx:
  customManifestPath: build/AppxManifest.xml

Or inject additional XML extensions:

appx:
  customExtensionsPath: build/appx-extensions.xml

Publishing to the Windows Store

1. Create a Microsoft Developer account ($19 one-time fee)
2. Reserve your app name in Partner Center
3. Build your AppX: electron-builder --win appx
4. Test the package locally (see Testing below)
5. Upload the .appx file via Partner Center submission
6. Complete the submission (age rating, pricing, screenshots, etc.)
7. Wait for Store certification (typically 1-3 business days)

Sideloading Without the Store

For enterprise distribution without the Store:

# Enable sideloading (Windows 10 1803+, this is the default)
# On Windows 10 S/SE, you must use the Store

# Install the AppX
Add-AppxPackage -Path ".\MyApp-1.0.0.appx"

If using a self-signed certificate, the user must trust it first (see "Common Questions" below).

Testing Locally

# Install locally (Developer Mode must be enabled for unsigned packages)
Add-AppxPackage -Path ".\MyApp-1.0.0.appx"

# Uninstall
Get-AppxPackage | Where-Object {$_.Name -like "*MyApp*"} | Remove-AppxPackage

Common Questions

How do I install an AppX with a self-signed certificate?

Import the certificate into "Trusted People" on the target machine — see Microsoft's guide to signing MSIX packages. Then install the AppX normally with Add-AppxPackage.

Does AppX support auto-updates without the Store?

No — AppX auto-updates are handled by the Windows Store only. electron-updater does not support AppX packages. For auto-updates outside the Store, use NSIS instead.

Configuration

Interface: AppXOptions

Extends

• TargetSpecificOptions

Properties

addAutoLaunchExtension?

readonly optional addAutoLaunchExtension?: boolean

Whether to add auto launch extension. Defaults to true if electron-winstore-auto-launch in the dependencies.

---

applicationId?

readonly optional applicationId?: string

The application id. Defaults to identityName. This string contains alpha-numeric fields separated by periods. Each field must begin with an ASCII alphabetic character.

---

artifactName?

readonly optional artifactName?: string | null

The artifact file name template.

Inherited from

TargetSpecificOptions.artifactName

---

backgroundColor?

readonly optional backgroundColor?: string | null

The background color of the app tile. See Visual Elements.

Default

#464646

---

capabilities?

readonly optional capabilities?: string[] | null

The list of capabilities to be added to an appmanifest.xml. The runFullTrust capability is obligatory for electron apps and will be auto added if not specified here. Defaults to ['runFullTrust'] if omitted Example: ['runFullTrust', 'privateNetworkClientServer', 'webcam']

---

customExtensionsPath?

readonly optional customExtensionsPath?: string

Relative path to custom extensions xml to be included in an appmanifest.xml.

---

customManifestPath?

readonly optional customManifestPath?: string

(Advanced Option) Relative path to custom appmanifest.xml (file name doesn't matter, it'll be renamed) located in build resources directory. Supports the following template macros:

• ${publisher}
• ${publisherDisplayName}
• ${version}
• ${applicationId}
• ${identityName}
• ${executable}
• ${displayName}
• ${description}
• ${backgroundColor}
• ${logo}
• ${square150x150Logo}
• ${square44x44Logo}
• ${lockScreen}
• ${defaultTile}
• ${splashScreen}
• ${arch}
• ${resourceLanguages}
• ${capabilities}
• ${extensions}
• ${minVersion}
• ${maxVersionTested}

---

displayName?

readonly optional displayName?: string | null

A friendly name that can be displayed to users. Corresponds to Properties.DisplayName. Defaults to the application product name.

---

identityName?

readonly optional identityName?: string | null

The name. Corresponds to Identity.Name. Defaults to the application name.

---

languages?

readonly optional languages?: string | string[] | null

The list of supported languages that will be listed in the Windows Store. The first entry (index 0) will be the default language. Defaults to en-US if omitted.

---

maxVersionTested?

readonly optional maxVersionTested?: string | null

Set the MaxVersionTested field in the appx manifest.xml

Default

arch === Arch.arm64 ? "10.0.16299.0" : "10.0.14316.0"

---

minVersion?

readonly optional minVersion?: string | null

Set the MinVersion field in the appx manifest.xml

Default

arch === Arch.arm64 ? "10.0.16299.0" : "10.0.14316.0"

---

publish?

optional publish?: Publish

Inherited from

TargetSpecificOptions.publish

---

publisher?

readonly optional publisher?: string | null

The Windows Store publisher. Not used if AppX is build for testing. See AppX Package Code Signing below.

---

publisherDisplayName?

readonly optional publisherDisplayName?: string | null

A friendly name for the publisher that can be displayed to users. Corresponds to Properties.PublisherDisplayName. Defaults to company name from the application metadata.

---

setBuildNumber?

readonly optional setBuildNumber?: boolean

Whether to set build number. See https://github.com/electron-userland/electron-builder/issues/3875

Default

false

---

showNameOnTiles?

readonly optional showNameOnTiles?: boolean

Whether to overlay the app's name on top of tile images on the Start screen. Defaults to false. (https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-uap-shownameontiles) in the dependencies.

Default

false