5
Watch
83
Star
21
Fork
6
Issue

Electron Wrapper to create Desktop Apps from offline-capable Progressive Web Apps

xtools-at
xtools-at
pushedAt 2 years ago

xtools-at/Electron-PWA-Wrapper

Electron PWA Wrapper

A sample wrapper app to package your Progressive Web App into a Desktop Application using Electron, Electon-Builder and Photon.

Drafted for the Desktop-version of my Leasing Calculator Web App using React, Redux, Materialize.css and a lot of Offline-First love over at leasingrechnen.at.

Looking for iOS or Android?

Check out my other projects:

Features

  • build with electron-builder for macOS, Windows and Linux
  • custom shell for each OS
  • macOS TouchBar support
  • handle connectivity issues natively in the wrapper

Wanna give it a try?

  • clone repository, cd into the directory
  • run npm install to get the dependencies
  • run npm run electron to start the app
  • check out /app/constants.js for more options (e.g. setting your own URL)

Basic Customizing

  • Place your Tray- and App-Icons into src/assets.
  • Change app/app_menu_template.js to use your own Menu Items.
  • Check app/constants.js for localizing your Strings (this project is German by default).
    • if you know how to do multi-language in Electron, a Pull-Request would be much appreciated!!
  • While in app/constants.js, check the settings and mainWindow sections too.
  • The Offline- and Loading-Screens are located in src/offline.html and src/loader.html, their corresponding images and styles in src/res.

Custom Shell

You can create a custom shell for your WebApp for each OS, to give it a more native look and feel or add functionality you can't supply from your WebApp, using Photon.

  • Go to src directory and find shellMacOS.html, shellWindows.html or shellLinux.html to see a sample implementation of the shell.
    • You'll need to customize the whole template to your needs! This is plain HTML, so your configured values in the constants.js won't work.
    • There's an example of a multi-column macOS shell with built-in navigation in src/shellMacOS-withMenu.html.
    • If you create new events, sent by the shell to the Main process, you'll have to listen for and handle them in /index.js.
  • In constants.json -> settings:
    • Locate usePhotonKitShell (macOS), useWindowsShell or useLinuxShell and enable accordingly.
    • Set nodeIntegrationEnabled to true.
    • Set frame to false for macOS. For other OS', it depends on how you create your shell. I wouldn't recommend disabling the frame on Windows, as this hides your native Menu completely.

Building with electron-builder

Electron-PWA-Wrapper comes with electron-builder preconfigured for macOS (dmg, mas), Linux (AppImage) and Windows (Appx + Portable).

Preperations

  • You'll need to
    • look up your package.json and put your App's values in the build section
    • and put all the required graphics into the build directory.
    • See below, and the electron-builder Docs for further details!
  • run npm run build or ./node_modules/.bin/electron-builder build to start the build. Your app files will be located in the dist folder.

Build for macOS App Store

  • Have a machine running latest macOS ready, and latest XCode installed.
  • Get a paid Apple Developer membership (~€99,- per year) and create Certificates, Identifiers and Provisioning Profiles for macOS:
    • Certificates: Production -> Mac App Distribution and Mac Installer Distribution.
    • Identifiers: App IDs -> create one with your package/bundle name (e.g. 'com.example.myawesomeapp').
    • Provisioning Profiles: Distribution -> Mac Distribution for the Identifier you just created.
  • Download the certificates and double-click them to get them installed in your local Keychain.
  • Download and copy your Provisioning Profile to the project root and rename it to embedded.provisionprofile.
  • Make sure you've updated your package.json->build-> appId, productName, copyright and mac->category
  • Put the required icons in place:
    • in build->icon.iconset, replace all the icons in the folder. Sizes and namings are important!
    • open the terminal, navigate to build and run the following command to create your icon.icns from the iconset you've just populated.
      • iconutil -c icns icon.iconset
  • Edit the build/Info.plist and build/entitlements.mas.plist and replace YourTeamId and YourPackageId.
    • You can find your Team ID on the Apple Developer Account in Membership.
    • Your package ID is the bundle identifier you've created in the step above (e.g. 'com.example.myawesomeapp').
  • Run npm run build from the terminal.
    • If it fails, you might have to give the process proper permission by running sudo ./node_modules/.bin/electron-builder build instead.

Build for Windows Store

  • Have a machine running Windows 10 Enterprise ready, with all latest updates and windows-build-tools installed.
  • Get a paid Windows Dev Center Publisher Account (~€25,- once) and sign up for DesktopBridge Support for your app.
  • Create your App in the Windows Dev Dasboard to get the values for the next step.
  • Update your package.json->build->win-> legalTrademarks and publisherName, and all the attributes in build->appx.
  • Put the required icons in place:
    • in build: icon.ico
    • in build/appx: replace all the icons in the folder. Sizes and namings are important!
  • Run npm run build from the command line (preferably from PowerShell).

Build for Linux (any distro, using AppImage)

  • Have a machine running up-to-date Ubuntu or Debian ready. Install Node.JS >= 6 as described here (or as you prefer).
  • Install build dependencies: sudo apt install -y icnsutils graphicsmagick
  • Create your build/icon.icns like described in Build for macOS App Store. Also, don't forget to place your Tray- and App-Icons into src/assets.
  • Update your package.json->build->linux and ->appImage.
  • Run npm run build and find your .AppImage in the dist folder.
  • Tell your users to run chmod a+x *.AppImage or to change permissions via GUI to make the file executable.

License

GNU General Public License v3.0 - if you use it, we wanna see it! Other licensing options are available on inquiry.

ucloud ads