Build cross-platform desktop apps with Electron
This is a workshop for learning how to build cross platform desktop apps with JavaScript, HTML, and CSS. We'll be using Electron to accomplish this.
Motivation
To help get you excited, take a look at some of the amazing apps that have already been built with Electron:
Atom | Slack | Visual Studio Code | Nylas N1 |
---|---|---|---|
WebTorrent | Brave | Hyper | Caprine |
---|---|---|---|
Keeweb | CryptoCat | ScreenCat | Playback |
---|---|---|---|
For more, take a look at this huge list of Electron apps.
Credit
Vast portions of this workshop are based on a similar workshop created by Steve Kinney. If you like it, check out his book Electron In Action.
Prerequisites
Electron apps build and run on Mac, Windows and Linux. You are free to choose your favorite operating system to run this tutorial.
Participants should have the latest version of Node.js installed. (The latest version is v6.x LTS.)
We'll primarily be working through one project today. But there is a second one, which is an opportunity to practice on your own after the workshop. The best way to get set up and ready to roll before the workshop is to clone this repository and run npm install
within it.
Markdown Editor
This is a tutorial for building a Markdown-to-HTML renderer using Electron. The final app will be similar to Markdownify.
Table of contents
- Getting Started and Acclimated
- Challenge 1: Hello World
- Challenge 2: Opening a File
- Challenge 3: Writing Renderer Code
- Challenge 4: Wiring Up the Buttons
- Challenge 5: Working with the Clipboard
- Challenge 6: Saving Files
- Challenge 7: Adding Menu Items
- Challenge 8: Electron's
shell
Module - Challenge 9: Appending to the Recent Documents Menu
- Challenge 10: Accessing the Outside World
- Challenge 11: Drag and Drop
- Challenge 12: More complete OS integrations
- Challenge 13: Package the app
- Challenge 14: Go crazy!
Getting Started and Acclimated
To get started, clone this repository and install the dependencies using npm install
.
We'll be working with four files for the duration of this tutorial:
lib/main.js
, which will contain code for the main processlib/renderer.js
, which will code for the renderer processlib/index.html
, which will contain the HTML for the user interfacelib/style.css
, which will contain the CSS to style the user interface
In a more robust application, you might break stuff into smaller files, butโfor the sake of simplicityโwe're not going to.
Challenge 1: Hello World
Now that we have our dependencies and some basic files, let's get our Electron application to the point where we can launch it.
Everything in Electron lives inside of the electron
library. Let's start by requiring it inside of main.js
.
const electron = require('electron')
Electron contains many modules that we'll use for building our application. The firstโand arguably, most importantโthat we're going to need is the app
module. All modules exist as properties on the electron
object. We're going to be using the app
module pretty often, so let's store it in its own variable.
const electron = require('electron')
const app = electron.app
The app
module has a number of life-cycle events. Here are a few examples:
Right now, displaying a user interface when the application is ready
is our primary concern. So, we'll listen for the ready
event and pass an arrow function that does some logging.
const electron = require('electron')
const app = electron.app
app.on('ready', () => {
console.log('The application is ready.')
})
There isn't much to look at yet, but if we run npm start
, you should notice the following.
- Our message is logged to the console.
- On Mac an Electron icon pops up in the Dock.
Hit Control-C
to kill the application.
Note: The npm start
command is just running electron .
for you. You can use electron .
directly, but you will need to install electron
globally with npm install -g electron
. In general, it's better to just use the locally-installed electron
binary. If you're curious, that binary exists at node_modules/.bin/electron
.
Firing Up a Renderer Process
Now that we can spin up our application, it's time to go ahead and build a user interface. In order to create a window for our application, we'll need to pull in the BrowserWindow
module.
const BrowserWindow = electron.BrowserWindow
We'll create the main window for our application when the application is ready. That said, we need to declare a variable to store our main window in the top level scope. This is due to the combination of two facts:
- JavaScript has function scopes.
- Our
ready
event listener is a function.
If we declared the mainWindow
variable in our event listener, it would be eligible for garbage collection as soon as that function is done executing, which is bad news. We'll declare mainWindow
in the top-level scope.
To avoid this, we'll update main.js
as follows:
const electron = require('electron')
const app = electron.app
const BrowserWindow = electron.BrowserWindow
let mainWindow = null
app.on('ready', () => {
console.log('The application is ready.')
mainWindow = new BrowserWindow()
mainWindow.on('closed', () => {
mainWindow = null
})
})
If the user ever closes the window, we'll set the mainWindow
back to null
.
Let's take our application for a spin again by running npm start
from the command line. You should see something resembling the image below.
Let's actually load some content, shall we?
Make sure you require the path
module towards the beginning of main.js
:
const path = require('path')
We'll also update the 'ready'
handler as follows:
app.on('ready', () => {
console.log('The application is ready.')
mainWindow = new BrowserWindow()
mainWindow.loadURL('file://' + path.join(__dirname, 'index.html'))
mainWindow.on('closed', function() {
mainWindow = null
})
})
In the code above, __dirname
is a globally-available Node variable that references the current directory that Node is running from. In this case, we're executing ./lib/main.js
, so __dirname
is the lib
directory relative to where ever you installed this repository.
Optional: Learn something extra!
These tasks are totally optional, but highly recommended to learn about some of Electron's more obscure, but powerful features.
-
Set the
width
andheight
of the browser window using options to theBrowserWindow
constructor to change the size of the window. -
Try to open the window at the top left of the screen, instead of in the center (which is default).
-
Try to change the title of the window. Electron supports two ways of setting the window title. The
BrowserWindow
constructor option will be used if the<title>
tag in the HTML is not specified. -
Try to make the window "float on top" so no other windows can be drawn above it.
-
Try to make the window "frameless". How will you allow the user to move around a frameless window if there's no title bar?
Challenge 2: Opening a File
One of the big motivations for building an Electron application is the promise of being able to do stuff we wouldn't normally be able to do in the browser. Prime examples are activating native OS dialogs and accessing the filesystem.
Actions like accessing the filesystem and calling native dialogs and menus are best handled by the main process. That said, we're eventually going to need to display the results in our renderer process as well as add buttons to our user interface for initiating the process of opening a file.
Let's start by adding some elements to the user interface for displaying our content once it's loaded.
In index.html
, replace the contents of <body>
with the following:
<section class="controls">
<button id="open-file">Open File</button>
<button id="copy-html">Copy HTML</button>
<button id="save-file">Save HTML</button>
</section>
<section class="content">
<textarea class="raw-markdown"></textarea>
<div class="rendered-html"></div>
</section>
We'll start by prompting the user for a file to open when the application is ready. In order to make this happen, we'll need Electron's dialog
module. Add the following to main.js
just below where we require our other Electron modules.
const dialog = electron.dialog
We're going to want to reuse this functionality, so we'll break it out into its own function.
function openFile () {
const files = dialog.showOpenDialog(mainWindow, {
properties: ['openFile']
})
if (!files) return
console.log(files)
}
We'll call this function immediately once the browser window has loaded. If the user cancels the file open dialog, files
will be undefined
. If that happens, we return early so that we don't get any errors down the line.
app.on('ready', () => {
console.log('The application is ready.')
mainWindow = new BrowserWindow()
mainWindow.loadURL('file://' + path.join(__dirname, 'index.html'))
// This event fires once the browser window's DOM is loaded
mainWindow.webContents.on('did-finish-load', () => {
openFile()
})
mainWindow.on('closed', function() {
mainWindow = null
})
})
Right now, we just log the name of the files selected to the console when we open a file. Try it out. You should notice that it's logging an array to the console. In theory, we're only going to want to open one file at a time in our application. So, we'll just grab the first file from the array.
function openFile () {
const files = dialog.showOpenDialog(mainWindow, {
properties: ['openFile']
})
if (!files) return
const file = files[0]
console.log(file)
}
Now that we have the location of our file, let's read from that location. fs.readFileSync
returns a Buffer
object. We know we're working with text. So, we'll turn that into a string using the toString()
method.
Make sure you require the fs
module towards the beginning of main.js
:
const fs = require('fs')
We'll also update openFile
as follows:
function openFile () {
const files = dialog.showOpenDialog(mainWindow, {
properties: ['openFile']
})
if (!files) return
const file = files[0]
const content = fs.readFileSync(file).toString()
console.log(content)
}
Go ahead and open a text file. You should see the contents of the file logged to the console. With Electron, we can limit the type of files we're willing to open by adding filters to the dialog.
const files = dialog.showOpenDialog(mainWindow, {
properties: ['openFile'],
filters: [
{ name: 'Markdown Files', extensions: ['md', 'markdown', 'txt'] }
]
})
You should now notice that images, PDFs and other assorted files that aren't text files are not available to be selected.
Sending Content to the Renderer Process
So, we can load files and log them to the terminal. That's great, but it's nothing we couldn't do in Node, right? We need to send the content we've loaded over to the render process.
Instead of logging to the console, let's send the content to the mainWindow
. Replace the console.log
in openFile
with the following:
mainWindow.webContents.send('file-opened', file, content)
This won't make anything appear in the window just yet, because we need to handle this event in renderer.js
, which we'll do in the next challenge!
Optional: Learn something extra!
-
Try setting a custom label for the
dialog
confirmation button. -
Try allowing multiple files to be selected in a single dialog box. See what kind of object gets returned by the callback.
Challenge 3: Writing Renderer Code
All of the code we've written so far has been in the main process. Now, it's time to write some code in the renderer process toโummโrender our content. Let's load up renderer.js
by adding the following to index.html
at the end of the body, right before </body>
. This means renderer.js
will be executed as last step of the page rendering and thus the script can access all the previously rendered DOM elements.
<script>
require('./renderer')
</script>
It's going to be helpful to have access to the Chrome Developer Tools in our renderer process. Let's have Electron pull those up when our browser window loads.
app.on('ready', () => {
// More code aboveโฆ
mainWindow.webContents.openDevTools()
// More code belowโฆ
})
(If this is distracting for you, feel free to remove this line, you'll be able to open these tools using the application's menus until we replace them later on this in tutorial.)
The main process and our renderer process are completely separate. In order to facilitate communication between the two, we need to use Electron's interprocess communication (IPC) protocol. In renderer.js
, we'll require Electron and the ipcRenderer
module.
const electron = require('electron')
const ipc = electron.ipcRenderer
When we load a file, the main process is sending our renderer process a message with the contents over the file-opened
channel. (This channel name is completely arbitrary and could very well be sandwich
.) Let's set up a listener.
ipc.on('file-opened', (event, file, content) => {
console.log(content)
})
You should now see the contents of the file you opened in the console of your renderer process in the Developer Tools.
Displaying Content on the Page
We'll use a shorthand for querySelector
in our renderer process to make things
a little more concise. We'll create a function named $
that gets a selector as parameter and returns the element. Let's create it in our renderer process as follows:
const $ = selector => document.querySelector(selector)
We'll also be a little proactive and cache selectors for our markdown view, rendered HTML view, and buttons.
const $markdownView = $('.raw-markdown')
const $htmlView = $('.rendered-html')
const $openFileButton = $('#open-file')
const $saveFileButton = $('#save-file')
const $copyHtmlButton = $('#copy-html')
When the renderer process gets a message on the file-opened
channel from the main process, we'll display those contents in the $markdownView
element.
ipc.on('file-opened', (event, file, content) => {
$markdownView.value = content
})
Next, we'll want to take that content, convert it to HTML, and display it in $htmlView
element. In our package.json
, we included the marked library to take care of the conversion for us. That said, we need to require it in renderer.js
.
const marked = require('marked')
We'll probably want to convert Markdown to HTML in multiple places in our application, so let's do it in a function that we can reuse later if we need to. Add the following to renderer.js
.
function renderMarkdownToHtml (markdown) {
const html = marked(markdown)
$htmlView.innerHTML = html
}
The first time we'll probably want to do this is when we load a Markdown file. Update your event listener as follows:
ipc.on('file-opened', (event, file, content) => {
$markdownView.value = content
renderMarkdownToHtml(content)
})
Open a file in the application and verify that it works.
Updating the HTML When the Markdown Changes
Whenever the user enters a key in the Markdown view, we'll want to update the HTML view to reflect the current state of the Markdown view. Let's listen for the keyup
event and reuse our renderMarkdownToHtml
function.
$markdownView.addEventListener('keyup', (event) => {
const content = event.target.value
renderMarkdownToHtml(content)
})
Challenge 4: Wiring Up the Buttons
In our application, we have three buttons in the top bar:
- Open File
- Copy HTML
- Save HTML
It's true that we already have the ability to open a file from within our applicationโbut only from the main process. Generally speaking, renderer processes should not access native OS APIs like spawning file dialogs and whatnot.
So, we're out of luck, right? Not quite. It's true that we can't pull up a file dialog from a renderer process. But, we can ask the main process to open one up on our behalf.
Electron comes with a remote
module, which allows us to pull in functionality from other processes. Let's require the remote
module in renderer.js
.
const remote = electron.remote
Once we have the remote module, we can use it to load up the main process.
const mainProcess = remote.require('./main')
Exporting Functionality
Requiring the main process is not enough. In Node, we need to be explicit about what functionality we're going to export from a module. As of right now, we haven't exported any functionality from main.js
. We want access to that openFile
function. So, let's go ahead and export that function in main.js
.
exports.openFile = openFile
Our openFile
function is now available on the mainProcess
object in renderer.js
.
$openFileButton.addEventListener('click', () => {
mainProcess.openFile()
})
When the "Open File" button is clicked, it will call the openFile
function from the main process and display the file dialog.
It's not necessary, but we can remove the call to openFile()
when the application starts up now that we have a way to do it from inside the application.
Optional: Learn something extra!
-
Read the docs for the
remote
module to learn more about how it actually works under the hood using IPC, and what the gotchas are. -
How can using the
remote
package result in a memory leak if you're not careful?
Challenge 5: Working with the Clipboard
Now that we have the first button in place, we'll go ahead and get the second button working.
The second button is labeled "Copy HTML." When it's working it should take the rendered HTML output and write it to the clipboard. It shouldn't be surprising to you when I say that Electron has a clipboard
module that makes it easy to work with the clipboard. Because it works with the OS's clipboard, we'll require it from the main process.
Let's require the clipboard
module in renderer.js
:
const clipboard = remote.clipboard
When the user clicks on the "Copy HTML" button, we'll go ahead and write the contents of the $htmlView
element to the clipboard.
$copyHtmlButton.addEventListener('click', () => {
const html = $htmlView.innerHTML
clipboard.writeText(html)
})
That's all that's required.
Challenge 6: Saving Files
We don't have a mechanism for saving files just yet. As I'm sure you might have guessed, this kind of functionality belongs in the main processโand we'll need to trigger it from the renderer process.
function saveFile (content) {
const fileName = dialog.showSaveDialog(mainWindow, {
title: 'Save HTML Output',
defaultPath: app.getPath('documents'),
filters: [
{ name: 'HTML Files', extensions: ['html'] }
]
})
if (!fileName) return
fs.writeFileSync(fileName, content)
}
We'll also want to export this functionality in main.js
:
exports.saveFile = saveFile
Pulling up the save dialog in the renderer process is almost the same as pulling up the open dialog, with the twist that we'll want to send off the data that we'd like written to the file system.
$saveFileButton.addEventListener('click', () => {
const html = $htmlView.innerHTML
mainProcess.saveFile(html)
})
We've successfully implemented a first pass at saving files to the filesystem with Electron.
Optional: Learn something extra!
-
Right now, each time we click the "Save HTML" button, we have to select the location to save the file. Make the app remember the last save location so clicking save again will just save to the same place, without showing the user a dialog. Also, when a file is opened, the first save should also not cause a prompt, but save to the same location.
-
Add a "Save As..." button, in addition to "Save". What's the difference between the two in most apps? (Side note: Why does "Save As..." have a ellipsis while "Save" does not? What does the ellipsis signify?)
Challenge 7: Adding Menu Items
Having a button for opening and saving files is pretty neat, but it's not the pattern we're used to in desktop applications. Typically, desktop applications have a "File" menu "Open" and "Save" items. Up to this point, Electron has given us some sensible defaults for menu items. (Fire up your application and check out the menu bar if haven't already.)
Let's go and pull in Electron's Menu
class. (This goes in main.js
.)
const Menu = electron.Menu
Unfortunately, Electron's default menu is a "take it or leave it" affair. The moment that we want to add our own custom functionality to the menu, we must first invent the universe. Electron does however give us the ability to create a simple data structure and have it build the menu from a template.
const menu = Menu.buildFromTemplate(template)
Once we have a menu object, we can override the default menu that Electron gave us when the app
fires it's ready
event.
app.on('ready', () => {
const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)
})
Now, this won't work because we don't have a template
object just yet. Because we have to recreate all of the default functionality, it's going to get a little verbose. I encourage you to copy and paste what follows and we'll discuss it together.
const template = [
{
label: 'File',
submenu: [
{
label: 'Open...',
accelerator: 'CmdOrCtrl+O',
click () { openFile() }
},
{
label: 'Save...',
accelerator: 'CmdOrCtrl+S',
click () {
// We can't call saveFile(content) directly because we need to get
// the content from the renderer process. So, send a message to the
// renderer, telling it we want to save the file.
mainWindow.webContents.send('save-file')
}
}
]
},
{
label: 'Edit',
submenu: [
{
label: 'Undo',
accelerator: 'CmdOrCtrl+Z',
role: 'undo'
},
{
label: 'Redo',
accelerator: 'Shift+CmdOrCtrl+Z',
role: 'redo'
},
{
type: 'separator'
},
{
label: 'Cut',
accelerator: 'CmdOrCtrl+X',
role: 'cut'
},
{
label: 'Copy',
accelerator: 'CmdOrCtrl+C',
role: 'copy'
},
{
label: 'Paste',
accelerator: 'CmdOrCtrl+V',
role: 'paste'
},
{
label: 'Select All',
accelerator: 'CmdOrCtrl+A',
role: 'selectall'
}
]
},
{
label: 'Developer',
submenu: [
{
label: 'Toggle Developer Tools',
accelerator: process.platform === 'darwin'
? 'Alt+Command+I'
: 'Ctrl+Shift+I',
click () { mainWindow.webContents.toggleDevTools() }
}
]
}
]
if (process.platform === 'darwin') {
const name = app.getName()
template.unshift({
label: name,
submenu: [
{
label: 'About ' + name,
role: 'about'
},
{
type: 'separator'
},
{
label: 'Services',
role: 'services',
submenu: []
},
{
type: 'separator'
},
{
label: 'Hide ' + name,
accelerator: 'Command+H',
role: 'hide'
},
{
label: 'Hide Others',
accelerator: 'Command+Alt+H',
role: 'hideothers'
},
{
label: 'Show All',
role: 'unhide'
},
{
type: 'separator'
},
{
label: 'Quit',
accelerator: 'Command+Q',
click () { app.quit() }
}
]
})
}
Welcome back! Let's take a closer look some of the moving pieces in the large chunk of code above. The template is an array of menu items. In this case, we have "File" and "Edit"โeach with their own submenus. Under "File," we have two menu items: "Save..." and "Open...". When clicked, the "Open..." menu item will call openFile
.
However, as the inline comment states, the "Save..." menu item works a little differently. We can't call saveFile(content)
directly in the main process like we did for openFile()
because we need to get the content to save from the renderer process. So, send a message to the renderer, telling it we want to save the file. Then it can call mainProcess.saveFile(html)
when it receives that message.
To handle the 'save-file' message, add the following to the renderer:
ipc.on('save-file', (event) => {
const html = $htmlView.innerHTML
mainProcess.saveFile(html)
})
We're also assigning each menu item an "accelerator" (also known as a shortcut or hot key).
In the "Edit" menu, we have some of the familiar commands: undo, redo, copy, cut, paste, select all. We probably don't want to reinvent the wheel. It would be great if each would do their normal thing. Electron allows us to define their "role," which will trigger the native OS behavior.
{
label: 'Copy',
accelerator: 'CmdOrCtrl+C',
role: 'copy'
}
You might also notice that we're defining the accelerator as "CmdOrCtrl+C". Electron will make the right choice on our behalf when it compiles for Mac, Windows, and/or Linux.
Application for Mac have an additional menu with the application's name and some common OS-specific menu items. We only want to add this menu if our Electron application is running on Mac.
if (process.platform === 'darwin') { โฆ }
Darwin is the UNIX foundation that Mac OS is built on. The process.platform
is baked into Node and returns 'darwin', 'freebsd', 'linux', 'sunos' or 'win32' depending on the platform it's being run from.
We'll use unshift
to push it onto the front of the array.
Note: Mac will stubbornly continue to use "Electron" as the application title. In order to override this, we'll have to adjust the plist
file that Electron generates when it builds the file, because that is what determines the application name on Mac OS. Modifying the plist
file is the same process we'll use for a custom application icon. We'll get to that later.
shell
Module
Challenge 8: Electron's We have a little bit of a bug in our application. If we have a link in our Markdown file and we click it, it will load inside of application which kind of ruins the illusion that we're building a native application. Even worse: we don't have a back button. So, we can't return to our regularly-schedule application. Luckily, Electron's shell
module allows us to access the OS's ability to open files as well as expose their location in the file system.
In renderer.js
, let's bring in Electron's shell
module:
const shell = electron.shell
Now, we'll listen for link clicks and ask them politely to open in a new window instead of stepping over our little application.
document.body.addEventListener('click', (event) => {
if (event.target.matches('a[href^="http"]')) {
event.preventDefault()
shell.openExternal(event.target.href)
}
})
Challenge 9: Appending to the Recent Documents Menu
Operating systems keep a record of recent files. We want our application to hook into this functionality. Doing this is fairly, simple. In our openFile
function, we'll add the following:
app.addRecentDocument(file)
As you can see, adding files to the list of recent documents is easy. What we haven't done is set up our application to open any of those files in the recent documents list when they're selected.
Whenever we select a file from the list of recent documents, app
fires an open-file
event. We can listen for this event, read the file, and then send it to the renderer process.
app.on('open-file', (event, file) => {
const content = fs.readFileSync(file).toString()
mainWindow.webContents.send('file-opened', file, content)
})
Optional: Learn something extra!
-
Take a look at the documentation for the methods in
app
. -
What other interesting OS integrations are available through that module that would be useful for a markdown editor?
Challenge 10: Accessing the Outside World
As we've seen with the recent documents list, one of the really cool things about Electron is that we can interact with the operating system around us. Let's add two more features to our app.
- A "Show in File System" button that will ask the operating system to show us where the markdown file is located on in either the Finder or Windows Explorer.
- A "Open in Default Editor" button that will open the current file in whatever application has designated as the default application for Markdown files.
To get started, we'll have to add these two buttons to the page. We'll update our controls section as follows:
<section class="controls">
<button id="open-file">Open File</button>
<button id="copy-html">Copy HTML</button>
<button id="save-file">Save HTML</button>
<button id="show-in-file-system" disabled="true">Show in File System</button>
<button id="open-in-default-editor" disabled="true">Open in Default Editor</button>
</section>
The final two buttons are the new buttons. The first three should be familiar from before. We've disabled them, because there is no active file when the application starts up. When the user opens a file, we'll have the main process inform the renderer process, which will then enable these buttons.
We'll also store a reference to each of them in renderer.js
.
const $showInFileSystemButton = $('#show-in-file-system')
const $openInDefaultEditorButton = $('#open-in-default-editor')
As we discussed earlier, Electron's shell
provides functionality to both the main and renderer processes that aides with desktop integration.
Activating the Buttons
Earlier we set up our main process to send the name of the file and its contents to the renderer process whenever it opened a new file. Let's go ahead and create a top-level variable to store the current file that's open so that we can reference it later.
In renderer.js
:
let currentFile = null
We'll also modify our file-opened
event listener to update currentFile
and enable the buttons.
ipc.on('file-opened', (event, file, content) => {
currentFile = file
$showInFileSystemButton.disabled = false
$openInDefaultEditorButton.disabled = false
$markdownView.value = content
renderMarkdownToHtml(content)
})
Then we need to use the shell
package again to actually implement the functionality:
$showInFileSystemButton.addEventListener('click', () => {
shell.showItemInFolder(currentFile)
})
$openInDefaultEditorButton.addEventListener('click', () => {
shell.openItem(currentFile)
})
Yea, that's actually it. Don't take my word for it. Verify that it works for yourself.
Challenge 11: Drag and Drop
Drag and drop on the window
Try dragging a random (.png, .jpg, .pdf, ertc.) file to the app window. What happens?
You should get a "save file" dialog. This is default browser behavior. Electron is trying to navigate the given file. Chrome also exhibits the same behavior. However, this isn't very useful for our app, so let's open drag-and-dropped files in the app, same as the "Open File" button.
Use the drag-drop
package to capture drop events on document.body
. The drag-drop
module automatically takes care of preventing the default browser event handler.
No code that you can just copy-paste for this one! You're an advanced workshopper from here on out. :-)
Once you've completed this challenge, verify that drag and drop works, then move on to the next challenge.
Drag and drop on the app icon (Mac)
Challenge 12: More complete OS integrations
Right-clicking on the app icon should show useful functionality, like an "Open File..." item. This is what an app icon menu looks like:
You can add a menu to the dock icon using the app.dock.setMenu(menu)
API for Mac. There is a similar feature on Windows called "User Tasks" that you can access via the app.setUserTasks(tasks)
API. For Linux, you can create a ".desktop" file that you can install into a special OS folder to add a menu to the app icon in the Unity Launcher.
Challenge 13: Package the app
Now, let's prepare the app to be shipped to real users. This is called "packaging" an app. Nearly all of the magic is handled by a package called electron-packager
.
You can quickly see it in action by running npm run package
. This will build an executable version of the application that works on the
current OS and architecture (e.g. Mac 64-bit, Windows 32-bit, Linux 64-bit, etc.).
Note: When you launch the executable on Mac, the menu bar should show the correct app title "Markdown Editor" now, not "Electron".
To build the app for all possible architectures, you can use npm run package-all
. Note: this can take a while because a ~40MB precompiled version of Electron must be downloaded for each OS/architecture combination. Currently this is:
- Mac, 64-bit
- Mac, app store build
- Windows, 64-bit
- Windows, 32-bit
- Linux, 64-bit
- Linux, 32-bit
- Linux, armv7l
One of the nicest things about electron-packager
is that you don't need to own a Mac, Windows, and Linux computer (or use VMs) in order to create binaries for each of these platforms, the way that most native app development works. Instead, electron-packager
downloads a precompiled Electron app and replaces the app
folder inside with the code from your app, and replaces the app icon with your app icon, if you have one. That's it.
Things get more complicated if you use a node module that contains native code. That's because that code needs to compiled separately for each platform. To keep things simple, try to avoid using modules that contain native code unless absolutely necessary. That will allow you to build for all platforms from any platform.
There are lots more advanced things you can support in your build process like:
- Create a Mac .DMG file for easier install, and compression
- Create a Windows installer, for easier install.
- Create a Windows "Portable App" build.
- Create a Debian/Ubuntu .deb file, for easier install.
You'll also want to sign the binaries that you produce. On Mac and Windows, it's very important to sign your binaries or the OS will show scary warnings to the user.
You can see how to do all these things and more by taking a look at the well-commented build file for WebTorrent Desktop.
Challenge 14: Go crazy!
If you finish early, here are some ideas for extra features to add:
-
Improve the UI. For example, try making the buttons at the top of the app look less like a web page. Removing the buttons entirely and putting their functionality into the app menu is a great idea.
-
Improve the UI, part 2. As another idea, try making the divider between the markdown and HTML views draggable so the user can set their size.
-
Add emoji support, like the vmd markdown editor has.
-
Add file watching support, like the vmd markdown editor has. Make it so local files that are opened are watched for changes and the viewer will automatically update when a file has been changed. This makes it ideal for writing documents in your favorite text editor so you get a live preview. In "watch mode", the editor textarea should be hidden since the user will using their own editor.