Skip to content

Instantly share code, notes, and snippets.

@steve981cr

steve981cr/How-to-Release-an-Electron-App-on-the-Microsoft-Store.md

Last active May 4, 2024 04:33
Show Gist options
  • Save steve981cr/52ca0ae39403dba73a7dbdbe5d231bbf to your computer and use it in GitHub Desktop.
Save steve981cr/52ca0ae39403dba73a7dbdbe5d231bbf to your computer and use it in GitHub Desktop.
Download ZIP
Step by step instructions on how to release an Electron app on the Microsoft Store. Uses Electron-builder to package the app.
Raw
How-to-Release-an-Electron-App-on-the-Microsoft-Store.md

How to Release an Electron App on the Microsoft Store

By Steve Carey - Last updated Sept 9, 2023.
Super basic app example: Github electron-app-store-example
To Do List app example (contains native node modules): github.com/steve981cr/electron-todo-example

Table of Contents

Introduction
Step 1) Start with your completed Electron Application
Step 2) Create icons of your logo
Step 3) Create Microsoft Developer Account and app
Step 4) package.json file
Step 5) Build the app and appx installer
Step 6) Test the Appx installer on your PC
Step 7) Publish your app in the Microsoft Store
Native Node NPM packages
Publish Updates to your app on the Microsoft Store

Introduction

You have two options for distributing an Electron App for Windows. Either directly or through the Microsoft Store. Below are the steps you need to take to get a basic app successfully submitted to be distributed on the Microsoft Store.

Step 1) Start with your completed Electron Application

Electron should be a development dependency.
npm install -D electron

Step 2) Create icons of your logo

Reference:
learn.microsoft.com/en-us/windows/uwp/app-resources/images-tailored-for-scale-theme-contrast learn.microsoft.com/en-us/windows/win32/uxguide/vis-icons

Icon Logo image files:

Main logo image:

Ref: electron.build/icons
You need to create at least one logo image sized 256x256px in png format. Convert it to ico format and place it in the build directory with the name build/icon.ico.

You can also just leave it in png format and place it in build/icon.png. Electron-builder will convert it to ico format and place it in dist/.icon-ico/icon.ico

This icon image is used on the app's Title Bar. If you don't create the Windows Store images below, then this image will be used for everything.

Windows Store images:

Ref: electron.build/configuration/appx#appx-assets
Create the below png image files and place them in the build/appx folder.

  • build/appx/StoreLogo.png
  • build/appx/Square150x150Logo.png
  • build/appx/Square44x44Logo.png. This image is used on the status bar and in the Window All Apps list.
  • build/appx/Wide310x150Logo.png

Step 3) Create Microsoft Developer Account and app

Reference: learn.microsoft.com/en-us/windows/apps/get-started/sign-up

You can register with an existing Microsoft Account or by creating a new Microsoft account: developer.microsoft.com/en-us/microsoft-store/register.
There is a fee of $19 for an individual, or $99 for a company. This is a one-time registration fee and no renewal is required.

Once you have an account, add your app:
Go to Apps and Games: partner.microsoft.com/en-us/dashboard/apps-and-games/overview
Click "New Product" > If it is a standard desktop app, select "EXE or MSI app" > Reserve a unique name for your app.

Step 4) package.json file

Change the values in angled brackets to your info and remove the brackets.

{ 
  "name": "<AppName>",
  "productName": "<App Name (can include spaces and special characters)>",
  "version": "<1.0.0>", 
  "scripts": {
    "start": "electron .",
    "dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
  },  
  ...
  "author": "<AuthorName>", 
  "build": {  
    "copyright": "Copyright © 202X <Developer or Company Name>",
    "files": [
      "!<file-or-directory-name-to-exclude>"
    ],
    "win": {
      "target": "appx"
    },
    "appx": {
      "identityName": "<12345Publishername.AppName>",
      "publisher": "<CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX>",
      "publisherDisplayName": "<Publisher Name>",
      "applicationId": "<Publishername.AppName>"
    }
  }
  ...
}

Properties:

Top level keys:

  • Name: The name key will be used as the display name for your app on the user's computer. It cannot contain spaces or special characters.
  • productName: If your app name does contain spaces or special characters then add a productName key.
  • Version number: Use semantic versioning - Major.Minor.Patch.
  • Scripts: are executed with npm run <scriptname>
    • The dist script launches electron-builder. It will automatically launche the win script if you are on a Windows PC, and the mac script if you are on a Mac. Optionally add the --win option to specify windows: "dist": electron-builder --win"
    • Only include the postinstall script above if you have native dependencies that need to be recompiled by Electron.

build property keys:

  • files: You can add an array of file and directory names to exclude from the build. Preface each name with a "!" to indicate that the file/directory should be excluded. Ref: electron.build/file-patterns

Appx Keys:

  • To get values for the identityName, publisher, and publisherDisplayName appx keys, go to your Microsoft Developer Dashboard: partner.microsoft.com/en-us/dashboard/home
    Click "Apps and Games" > Click your app name > Click "Product Identity".
    There will be a section that says "Include these values in your package manifest".
  • identityName: Use "Package/Identity/Name". Ref
  • publisher: Use "Package/Identity/Publisher". Ref
  • publisherDisplayName: Use "Package/Properties/PublisherDisplayName". Ref
  • displayName: Optional friendly name to display to users. Default is the productName or the name property. Ref

Reference:

Step 5) Build the app and appx installer

In PowerShell or another Command Line Interface, cd to the project root directory. Then run the build script: npm run dist

If you get a "command not found" error, then include the relative path. Here are the direct commands with the path:
Mac: ./node_modules/.bin/electron-builder
Windows: .\node_modules\.bin\electron-builder.cmd

This should create two builds:

  1. A development executable application you can open just by double-clicking it: build/win-unpacked/AppName.exe
  2. An AppX application installer located in: build/AppName 1.0.0.appx

When you submit the installer to the Microsoft Store, it will get digitally signed. So you don't need to digitally sign it yourself unless you want to test it on your development PC (see Step 6).

Step 6) Test the Appx installer on your PC

You should test the appx installer on your PC before submitting it to the Microsoft Store. To do that you need to create a self-signed certificate and digitally sign the appx installer.
You need to install SignTool which is part of the Windows SDK. See Self Sign a Windows Desktop Application with SignTool for details.

Step 7) Publish your app in the Microsoft Store

Reference: learn.microsoft.com/en-us/windows/apps/publish/publish-your-app/overview

Go to your app dashboard: partner.microsoft.com/en-us/dashboard/apps-and-games > click your App.

  • Fill out all the categories: Pricing, Properties, Age ratings, Store listings.

  • Include screenshots in Store Listings. Must be taken in a Windows environment. 1366 x 768 pixels or larger recommended. Supports 4K images (3840 x 2160).

  • Upload your appx file: Click Packages > Drag and Drop the file into the designated area > click Save button.

  • Then click the Submit to the Store button. Under Submission options you can set it to publish automatically when approved, or you can publish it manually by clicking the Publish button when ready.

  • When published, your app will be visible on the Microsoft Store at: https://www.microsoft.com/store/apps/YourAppID

Native Node NPM packages

Reference: electronjs.org/docs/latest/tutorial/using-native-node-modules

Native node modules are npm packages that include C or C++ code.
C/C++ code must be compiled into executable binaries. Even if the modules are precompiled when installed, they must be recompiled for Electron. Electron-builder will do that automatically when you run the electron-builder script npm run dist.
To recompile native modules in development, you can add the below script to your package.json file:

"postinstall": "electron-builder install-app-deps"

Then after installing native modules, run the script: npm run postinstall

Matching System and Electron Node.js versions

If you are using NPM packages that include native modules, you may encounter issues if your system Node version is different than the version in your Electron package. If you run into this issue, you can fix this by updating your system Node version or changing your Electron version so that the Node versions match.

To see what your system's Node version is run: node --version
Electron ships with its own Node.js version. To see what version of Node it uses, in your main file add the following log:
console.log('Node Version:', process.versions['node']);

Electron releases a new major version every time they upgrade the Nodejs version. For example, Electron version 24.0.0 uses node 18.14.0. To see what version of Node each electron version uses, go to the release notes: releases.electronjs.org/releases/stable.

Publish Updates to your app on the Microsoft Store

Reference: learn.microsoft.com/en-us/windows/apps/publish/publish-your-app/publish-update-to-your-app-on-store

  • Starting with your updated electron app.
  • Package.json file: Change the version number: (e.g., "version": "1.1.0",)
  • Get the latest electron-builder version: npmjs.com/package/electron-builder. Update to the latest electron-builder version. npm install -D electron-builder@X.X.X
  • Build the appx installer: npm run dist
  • Go to partner.microsoft.com/en-us/dashboard/apps-and-games > Click on your app name > Under "Action" click "Update" > click Packages > Drag and Drop the appx installer file into the designated area > click Save button.
  • Make any changes to the Pricing, Properties, Age ratings, Store listings you want to make. Then click the Submit to the Store button. Under Submission options you can set it to publish automatically when approved, or you can publish it manually by clicking the Publish button when ready.
  • Microsoft keeps 15% of the purchase price.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment