Installing Web Apps with Electron

There used to be a clear distinction between “applications” and “websites.”

  • apps — installable binary packages targeted at specific computing platforms that stay on the device until removed
  • websites — served-out HTML/JavaScript/CSS pages rendered on a client-side web browser

Now we have “progressive web apps” (PWAs) that are much more than static web pages. They aim to be installable, operated offline, and have app-like features (notifications, background tasks, sync, etc.), while still being delivered through a web browser.

The PWA movement is making leaps and bounds, but if you are a web developer and want to create native, installable applications for Mac, Windows, and Linux today, then the Electron framework may be for you. It is a framework used to build the Slack and Microsoft Visual Studio Code apps.

Simply build an HTML/JavaScript/CSS web app, which as a bonus can include npm modules from the Node.js world, and Electron packages the whole thing up as a native, installable application package. Apps get their own icon (merrily bouncing away in a Mac’s dock) and can be automatically updated and have access to native menus, file selectors, and other APIs.

My first Electron App

As my first Electron project, I thought I’d make a simple but useful utility out of components that I already had. I used my couchimport library, which imports structured data into CouchDB/Cloudant, to create a desktop app.

The user interface is as simple as can be: run the app, drag and drop a CSV file, and watch as it is imported into a local CouchDB database or a remote Cloudant cluster.

The structure of an Electron app

If you’ve built Node.js applications before, you know that your app’s meta data and dependencies are stored in a package.json file. In an Electron app, there are two package.json files:

  • Development package.json - defines the dependencies required to build the Electron executable and installer
  • Application package.json - your app's dependencies

Typically, your source code directory would look like this…


…with your web application residing in the app sub-directory. Although Electron's own Quick Start project isn't organised this way, it's a very neat way of separating out the framework's dependencies from yours and is worth adopting from the beginning.

Electron-ifying a web app

Typically, a simple Electron app has main.js which is the application's entry point. It opens a web page as its main window.

While Electron keeps out of your web app’s way for the most part, there are some Electron-specific features that you need to consider for your app:

  • if you want your app to have native menus, then you need to define them in your application’s main.js
  • to activate native file selectors from your app, you must delve into the Electron APIs
  • if you want anchor tags to open in a browser window, use the Electron shell API
  • to store state (such as your application’s config) between runs, then you need something like electron-config to persist the data locally

Otherwise your static HTML/JavaScript/CSS application can turn into a native app before your eyes.

Running locally

Clone your project’s repository and run npm install to load the Electron code and your application's dependencies:

git clone
cd couchdbimporter
npm install

Run your app with npm start

npm start

Making an installer

If you want to distribute your application, then you need an ‘installer’ for each operating system platform. I have my ‘package.json’ set up so that it creates an Apple Mac installer with

npm run mac

and the resultant files are stored in the dist/mac directory.

The same process can be run for win and linux targets to produce installers for Windows and Linux, respectively.

It is also possible to script the build and deployment your app installers.

Alternatives to Electron

The Electron framework is a powerful way of making native apps for multiple platforms with your web app skill set while avoiding cross-browser issues. But it isn’t the only pony in the show:

  • Progressive Web Apps are web sites that can offer app-like features and are accessed by a URL
  • there are already tools that allow websites to behave like desktop applications (by encasing them in an Electron wrapper)
  • Cordova lets you build web applications as native mobile applications for iOS and Android
  • React Native is another way to build native mobile applications from web technology, as is NativeScript

Try it yourself

Take a look at my CouchDB data importer app, and then try this with your own app. If you liked this article, express yourself with a click on the ♡. Thanks.