Steve Kinney MANNING Electron in Action Electron in Action STEVEN KINNEY MANNING SHELTER ISLAND For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 Email: [email protected] ©2019 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. Manning Publications Co. Development editor: Helen Stergius 20 Baldwin Road Technical development editor: Nickie Buckner PO Box 761 Review editor: Aleksandar Dragosavljevic´ Shelter Island, NY 11964 Project editor: Lori Weidert Copy editor: Pamela Hunt Proofreader: Elizabeth Martin Technical proofreader: Doug Warren Typesetter: Dennis Dalinnik Cover designer: Marija Tudor ISBN: 9781617294143 Printed in the United States of America 12345678910–DP–232221201918 This book is dedicated to my wife, Logan, and my sons, Wes and Jack. You are the loves of my life. brief contents PART 1GETTING STARTED WITH ELECTRON ..............................1 1 ■ Introducing Electron 3 2 ■ Your first Electron application 17 PART 2BUILDING CROSS-PLATFORM APPLICATIONS WITH ELECTRON .........................................................45 3 ■ Building a notes application 47 4 ■ Using native file dialog boxes and facilitating interprocess communication 65 5 ■ Working with multiple windows 87 6 ■ Working with files 98 7 ■ Building application and context menus 123 8 ■ Further operating system integration and dynamically enabling menu items 143 9 ■ Introducing the tray module 159 10 ■ Building applications with the menubar library 181 11 ■ Using transpilers and frameworks 199 vii viii BRIEF CONTENTS 12 ■ Persisting use data and using native Node.js modules 222 13 ■ Testing applications with Spectron 243 PART 3DEPLOYING ELECTRON APPLICATIONS .......................257 14 ■ Building applications for deployment 259 15 ■ Releasing and updating applications 272 16 ■ Distributing your application through the Mac App Store 293 contents preface xvii acknowledgments xix about this book xxi about the cover illustration xxv PART 1GETTING STARTED WITH ELECTRON ....................1 Introducing Electron 3 1 1.1 What is Electron? 4 What is the Chromium Content Module? 5 ■ What is Node.js? 6 1.2 Who’s using Electron? 6 1.3 What do I need to know? 8 1.4 Why should I use Electron? 8 Building on your existing skill set 9 ■ Access to native operating system APIs 10 ■ Enhanced privileges and looser restrictions 10 Accessing Node from the browser context 13 ■ Offline first 13 1.5 How does Electron work? 13 The main process 14 ■ Renderer processes 14 1.6 Electron vs. NW.js 15 ix x CONTENTS Your first Electron application 17 2 2.1 Building a bookmark list application 18 Structuring the Electron application 19 ■ package.json 20 Downloading and installing Electron in our project 21 2.2 Working with the main process 23 2.3 Creating a renderer process 24 Loading code from the renderer process 26 ■ Requiring files in the renderer process 29 ■ Adding styles in the renderer process 29 2.4 Implementing the UI 30 Making cross-origin requests in Electron 32 ■ Parsing responses 33 ■ Storing responses with web storage APIs 34 Displaying request results 35 ■ The unhappy path 38 An unexpected bug 40 PART 2BUILDING CROSS-PLATFORM APPLICATIONS WITH ELECTRON ...............................................45 Building a notes application 47 3 3.1 Defining our application 48 3.2 Laying the foundation 49 3.3 Bootstrapping the application 51 Implementing the UI 51 ■ Gracefully displaying the browser window 56 3.4 Implementing the base functionality 57 3.5 Debugging an Electron application 59 Debugging renderer processes 59 ■ Debugging the main process 61 ■ Debugging the main process with Visual Studio Code 61 Using native file dialog boxes and facilitating interprocess 4 communication 65 4.1 Triggering native file dialog boxes 66 4.2 Reading files using Node 69 Scoping the Open File dialog 70 ■ Implementing dialog sheets in macOS 71 4.3 Facilitating interprocess communication 74 Introducing the remote module 77 CONTENTS xi 4.4 Triggering the Open File function using interprocess communication 79 Understanding the CommonJS require system 79 ■ Requiring functionality from another process 79 4.5 Sending content from the main process to the renderer process 81 Sending the file contents to the renderer contents 82 Working with multiple windows 87 5 5.1 Creating and managing multiple windows 88 Communicating between the main process and multiple windows 90 ■ Passing a reference to the current window to the main process 91 5.2 Improving the user experience of creating new windows 93 5.3 Integrating with macOS 95 Working with files 98 6 6.1 Keeping track of the current file 99 Updating the window title based on the current file 101 Determining whether the current file has changed 103 Enabling the Save and Revert buttons in the UI 105 Updating the represented file on macOS 105 6.2 Tracking recently opened files 106 6.3 Saving files 108 Exporting the rendered HTML output 109 ■ Common paths 110 ■ Saving files from the renderer process 110 Saving the current file 111 ■ Reverting files 112 6.4 Opening files using drag and drop 112 Ignoring dropped files everywhere else 113 ■ Providing visual feedback 113 ■ Opening dropped files 116 6.5 Watching files for changes 117 6.6 Prompting the user before discarding changes 119 Building application and context menus 123 7 7.1 Replacing and replicating the default menu 125 macOS and the case of the missing Edit menu 126 The hidden cost of replacing Electron’s default menu 128 xii CONTENTS Implementing the Edit and Window menus 129 ■ Defining menu item roles and keyboard shortcuts 130 ■ Restoring the application menu on macOS 131 ■ Adding a Help menu 134 7.2 Adding application-specific menu functionality 136 Handling the case of having no focused window 138 7.3 Building context menus 140 Further operating system integration and dynamically 8 enabling menu items 143 8.1 Using the shell module from the UI in the renderer process 145 8.2 Using the shell module in the application menu 146 Additional features of the Electron shell module 148 8.3 Accessing the shell module from a context menu 148 Deciding between putting functionality in a menu or in the browser 149 ■ Deciding between putting functionality in the application or context menu 150 8.4 Disabling menu items when appropriate 150 Dynamically enabling and disabling menu items in the context menu 150 ■ Dynamically enabling and disabling menu items in the application menu 153 Introducing the tray module 159 9 9.1 Getting started with Clipmaster 161 9.2 Creating an application with the tray module 161 Using the correct icon for macOS and Windows 163 Supporting dark mode in macOS 164 ■ Reading from the clipboard and storing clippings 164 9.3 Reading from and writing to the clipboard 167 Writing to the clipboard 168 ■ Handling edge cases 170 9.4 Registering global shortcuts 172 Checking registrations and unregistering global shortcuts 174 9.5 Displaying notifications 174 9.6 Switching menu bar icons when pressed in macOS 177 9.7 Completed code 178 CONTENTS xiii Building applications with the menubar library 181 10 10.1 Starting an application with menubar 182 10.2 Adding clippings to the UI 186 10.3 Working with clippings in the application 188 Preventing memory leaks using event delegation 188 Removing a clipping 189 ■ Writing to the clipboard 190 10.4 Publishing clippings 191 Setting up request 192 10.5 Displaying notifications and registering global shortcuts 193 Registering global shortcuts 194 ■ Solving for the edge case that occurs if the window has never been shown 196 10.6 Adding a secondary menu 197 Using transpilers and frameworks 199 11 11.1 Introducing electron-compile 201 11.2 Laying the application’s foundation 202 11.3 Building the UI in React 207 The Application component 208 ■ Displaying the lists of items 210 11.4 Adding new items 214 11.5 Live reload and hot module reloading 217 Enabling live reload 217 ■ Setting up hot module reloading 218 Persisting user data and using native Node.js modules 222 12 12.1 Storing data in an SQLite database 223 Using the right versions with electron-rebuild 224 ■ Setting up SQLite and Knex.js 224 ■ Hooking the database into React 226 Fetching all of the items from the database 227 ■ Adding items to the database 228 ■ Updating items in the database 230 Deleting items 232 ■ Storing the database in the right place 235 12.2 IndexedDB 236 Creating a store with IndexedDB 236 ■ Getting data from IndexedDB 237 ■ Writing data