# Electron Apps in the Windows Store ## [**Disclaimer**] This repository is forked from [Electron Windows Store](https://github.com/felixrieseberg/electron2appx.git) due to its inactivity, to suit my own use of submitting appx to Windows Store. Please use as is. I am not an official maintainer of this project and may not have time to solve the peculiar issues that other users could be facing. That said, your [support](https://www.buymeacoffee.com/bl5s3cxyr) is always welcome. Thanks! --- electron2appx: A CLI that takes the packaged output of your Electron app, then converts it into an AppX package. This allows you to submit your Electron app to the Windows Store :package:. You can also distribute your app as an `.appx` without using the Windows Store, allowing users to just double-click your `.appx` to automatically install it. ![main_image](https://cloud.githubusercontent.com/assets/1426799/15042115/3471f6a0-12b9-11e6-91b4-80f25ec1d0b8.jpg) To install this command line tool, get it directly from npm: npm install -g electron2appx Then, configure your PowerShell: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned To turn an Electron app into an AppX package, run: electron2appx --input-directory C:\myelectronapp --output-directory C:\output\myelectronapp --package-version 1.0.0.0 --package-name myelectronapp This tool supports two methods to create AppX packages: Either using manual file copy operations, or using Windows Containers. The first option requires only the [Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk), while the second option also requires the [Desktop App Converter](https://docs.microsoft.com/en-us/windows/uwp/porting/desktop-to-uwp-run-desktop-app-converter). # Usage Before running the electron2appx CLI, let's make sure we have all the prerequisites in place. You will need: - Windows 10 with at least the Anniversary Update (if your Windows has been updated before 2018, you're good). - Windows 10 SDK from [here](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) - Node 8 or above (to check, run `node -v`) ## Package Your Electron Application Package the application using [electron-packager](https://github.com/electron-userland/electron-packager) (or something similar). Make sure to remove node_modules that you don't need in your final application. The output should look roughly like this: ``` ├── Ghost.exe ├── LICENSE ├── content_resources_200_percent.pak ├── node.dll ├── pdf.dll ├── resources │   ├── app │   └── atom.asar ├── snapshot_blob.bin ├── [... and more files] ``` ## Convert with File Copying **From an elevated PowerShell (run it "as Administrator")**, run `electron2appx` with the required parameters, passing both the input and output directories, the app's name and version. If you don't pass these parameters, we will simply ask you for them. electron2appx --input-directory C:\myelectronapp --output-directory C:\output\myelectronapp --package-version 1.0.0.0 --package-name myelectronapp These are all options for the CLI: ``` -h, --help output usage information -V, --version output the version number -c, --container-virtualization Create package using Windows Container virtualization -b, --windows-build Display Windows Build information -i, --input-directory Directory containing your application -o, --output-directory Output directory for the appx -p, --package-version Version of the app package -n, --package-name Name of the app package --package-display-name Display name of the package --package-description Description of the package --package-background-color Background color for the app icon (example: #464646) -e, --package-executable Path to the package executable -a, --assets Path to the visual assets for the appx -m, --manifest Path to a manifest, if you want to be overwritten -d, --deploy Should the app be deployed after creation? --application-id Application ID, only A-Za-z0-9. are allowed --identity-name Name for identity --publisher Publisher to use (example: CN=developmentca) --publisher-display-name Publisher display name to use --make-pri Use makepri.exe (you don't need to unless you know you do) --windows-kit Path to the Windows Kit bin folder --dev-cert Path to the developer certificate to use OR nil if no signing wanted, i.e. windows store submission --cert-pass Password to use when signing the application (only necessary if a p12 certication is used) --desktop-converter Path to the desktop converter tools --expanded-base-image Path to the expanded base image --makeappx-params Additional parameters for Make-AppXPackage (example: --makeappx-params "/l","/d") --signtool-params Additional parameters for signtool.exe (example: --makeappx-params "/l","/d") --create-config-params Additional parameters for makepri.exe "createconfig" (example: --create-config-params "/l","/d")') --create-pri-params Additional parameters for makepri.exe "new" (example: --create-pri-params "/l","/d")') --verbose Enable debugging (similar to setting a DEBUG=electron2appx environment variable) ``` ### Windows Store Submission As Windows Store submission requires unsigned appx, you can use the `--dev-cert nil` to bypass signing. application-id is only needed when there are spaces or other characters in package-name that are not accepted by makeappx. ### Assets As per [Windows App icons and logos](https://docs.microsoft.com/en-us/windows/apps/design/style/app-icons-and-logos), you should supply your own icon png files in a folder via `--assets` option to override this tool's default icon files: - Square150x150Logo.png - Wide310x150Logo.png - Square44x44Logo.png - SmallTile.png - LargeTile.png (not supplied) ## Programmatic Usage You can call this package directly. All options correspond to the CLI options and are equally optional. There is one exception: You can provide a `finalSay` function, which will be executed right before `makeappx.exe` is being called. This allows you to modify the output folder right before we turn it into a package. ```js const convertToWindowsStore = require('electron2appx') convertToWindowsStore({ containerVirtualization: false, inputDirectory: 'C:\\input\\', outputDirectory: 'C:\\output\\', packageVersion: '1.0.0.0', packageName: 'Ghost', packageDisplayName: 'Ghost Desktop', packageDescription: 'Ghost for Desktops', packageExecutable: 'app/Ghost.exe', assets: 'C:\\assets\\', manifest: 'C:\\AppXManifest.xml', deploy: false, publisher: 'CN=developmentca', windowsKit: 'C:\\windowskit', devCert: 'C:\\devcert.pfx', certPass: 'abcd', desktopConverter: 'C:\\desktop-converter-tools', expandedBaseImage: 'C:\\base-image.wim', makeappxParams: ['/l'], signtoolParams: ['/p'], makePri: true, createConfigParams: ['/a'], createPriParams: ['/b'], finalSay: function () { return new Promise((resolve, reject) => resolve()) } }) ``` ## Convert with Container Virtualization The Desktop App Converter is capable of running an installer and your app during conversion inside a Windows Container. This requires installation of the Desktop App Converter and has more advanced requirements. :warning: The _vast majority_ of Electron apps should be packaged using "File Copying". Unless you know that you need your `appx` to be created using a Windows container, use the "File Copying" method described above. :computer: Ensure that your computer is capable of running containers: You'll need a 64 bit (x64) processor, hardware-assisted virtualization and second Level Address Translation (SLAT). You will also need Windows 10 Enterprise Edition. :bulb: Before running the CLI for the first time, you will have to setup the "Windows Desktop App Converter". This will take a few minutes, but don't worry - you only have to do this once. Download and the Desktop App Converter from [here](https://docs.microsoft.com/en-us/windows/uwp/porting/desktop-to-uwp-run-desktop-app-converter). You will receive two files: `DesktopAppConverter.zip` and `BaseImage-14316.wim`. 1. Unzip `DesktopAppConverter.zip`. From an elevated PowerShell (opened with "run as Administrator"., ensure that your systems execution policy allows us to run everything we intended to run by calling `Set-ExecutionPolicy bypass`. 2. Then, run the installation of the Desktop App Converter, passing in the location of the Windows .ase Image (downloaded as `BaseImage-14316.wim`), by calling `.\DesktopAppConverter.ps1 -Setup -BaseImage .\BaseImage-14316.wim`. 3. If running the above command prompts you for a reboot, please restart your machine and run the above command again after a successful restart. Then, run `electron2appx` with the `--container-virtualization` flag! ### What is the CLI Doing? Once executed, the tool goes to work: It accepts your Electron app as an input. Then, it archives your application as `app.zip`. Using an installer and a Windows Container, the tool creates an "expanded" AppX package - including the Windows Application Manifest (`AppXManifest.xml`) as well as the virtual file system and the virtual registry inside your output folder. Once we have the expanded AppX files, the tool uses the Windows App Packager (`MakeAppx.exe`) to create a single-file AppX package from those files on disk. Finally, the tool can be used to create a trusted certificate on your computer to sign the new AppX pacakge. With the signed AppX package, the CLI can also automatically install the package on your machine. ## Configuration :bulb: The first time you run this tool, it needs to know some settings. It will ask you only once and store your answers in your profile folder in a `.electron2appx` file. You can also provide these values as a parameter when running the CLI. ```json { "publisher": "CN=developmentca", "windowsKit": "C:\\Program Files (x86)\\Windows Kits\\10\\bin\\x64", "devCert": "C:\\Tools\\DesktopConverter\\Certs\\devcert.pfx", "desktopConverter": "C:\\Tools\\DesktopConverter", "expandedBaseImage": "C:\\ProgramData\\Microsoft\\Windows\\Images\\BaseImage-14316\\" } ``` ## Using all the fancy Windows APIs You can pair up your Electron app with a little invisible UWP side-kick, enabling your Electron app to call all WinRT APIs. Check out [an example over here](https://github.com/felixrieseberg/electron-uwp-background). ## Devices The compiled AppX package still contains a win32 executable - and will therefore not run on Xbox, HoloLens, or Phones. ## Development `electron2appx` uses [Semantic Release](https://github.com/semantic-release/semantic-release) to automate the whole release process. In order to have a PR merged, please ensure that your PR follows the commit guidelines so that our robots can understand your change. This repository uses the [default `conventional-changelog` rules](https://www.conventionalcommits.org/en/v1.0.0-beta.2/). ## License Licensed using the MIT License (MIT); Copyright (c) Felix Rieseberg and Microsoft Corporation. For more information, please see [LICENSE](LICENSE).