The first commit to the electron/electron repository was on March 13, 2013¹.

10 years and 27,147 more commits from 1192 unique contributors later, Electron has become one of the most popular frameworks for building desktop applications today. This milestone is the perfect opportunity to celebrate and reflect on our journey so far, and to share what we’ve learned along the way.

We would not be here today without everyone who has dedicated their time and effort to contribute to the project. Although source code commits are always the most visible contributions, we also have to acknowledge the effort of folks who report bugs, maintain userland modules, provide documentation and translations, and participate in the Electron community across cyberspace. Every contribution is invaluable to us as maintainers.

Before we continue with the rest of the blog post: thank you. ❤️

How did we get here?​

Atom Shell was built as the backbone for GitHub’s Atom editor, which launched in public beta in April 2014. It was built from the ground up as an alternative to the web-based desktop frameworks available at the time (node-webkit and Chromium Embedded Framework). It had a killer feature: embedding Node.js and Chromium to provide a powerful desktop runtime for web technologies.

Within a year, Atom Shell began seeing immense growth in capabilities and popularity. Large companies, startups, and individual developers alike had started building apps with it (some early adopters include Slack, GitKraken, and WebTorrent), and the project was aptly renamed to Electron.

From then on, Electron hit the ground running and never stopped. Here’s a look at our weekly download count over time, courtesy of npmtrends.com:

Electron v1 was released in 2016, promising increased API stability and better docs and tooling. Electron v2 was released in 2018 and introduced semantic versioning, making it easier for Electron developers to keep track of the release cycle.

By Electron v6, we shifted to a regular 12-week major release cadence to match Chromium’s. This decision was a change in mentality for the project, bringing “having the most up-to-date Chromium version” from a nice-to-have to a priority. This has reduced the amount of tech debt between upgrades, making it easier for us to keep Electron updated and secure.

Since then, we’ve been a well-oiled machine, releasing a new Electron version on the same day as every Chromium stable. By the time Chromium sped up their release schedule to 4 weeks in 2021, we were able to shrug our shoulders and increase our release cadence to 8 weeks accordingly.

We’re now on Electron v23 (and counting), and are still dedicated to building the best runtime for building cross-platform desktop applications. Even with the boom in JavaScript developer tools in recent years, Electron has remained a stable, battle-tested stalwart of the desktop app framework landscape. Electron apps are ubiquitous nowadays: you can program with Visual Studio Code, design with Figma, communicate with Slack, and take notes with Notion (amongst many other use cases). We’re incredibly proud of this achievement and grateful to everyone who has made it possible.

What did we learn along the way?​

The road to the decade mark has been long and winding. Here are some key things that have helped us run a sustainable large open source project.

Scaling distributed decision-making with a governance model​

One challenge we had to overcome was handling the long-term direction of the project once Electron first exploded in popularity. How do we handle being a team of a couple dozen engineers distributed across companies, countries, and time zones?

In the early days, Electron’s maintainer group relied on informal coordination, which is fast and lightweight for smaller projects, but doesn’t scale to wider collaboration. In 2019, we shifted to a governance model where different working groups have formal areas of responsibility. This has been instrumental in streamlining processes and assigning portions of project ownership to specific maintainers. What is each Working Group (WG) responsible for nowadays?

• Getting Electron releases out the door (Releases WG)
• Upgrading Chromium and Node.js (Upgrades WG)
• Overseeing public API design (API WG)
• Keeping Electron secure (Security WG)
• Running the website, documentation, and tooling (Ecosystem WG)
• Community and corporate outreach (Outreach WG)
• Community moderation (Community & Safety WG)
• Maintaining our build infrastructure, maintainer tools, and cloud services (Infrastructure WG)

Around the same time we shifted to the governance model, we also moved Electron's ownership from GitHub to the OpenJS Foundation. Although the original core team still works at Microsoft today, they are only a part of a larger group of collaborators that form Electron governance.

While this model isn’t perfect, it has suited us well through a global pandemic and ongoing macroeconomic headwinds. Going forward, we plan on revamping the governance charter to guide us through the second decade of Electron.

Community​

The community part of open source is hard, especially when your Outreach team is a dozen engineers in a trench coat that says “community manager”. That said, being a large open source project means that we have a lot of users, and harnessing their energy for Electron to build a userland ecosystem is a crucial part of sustaining project health.

What have we been doing to develop our community presence?

Building virtual communities​

• In 2020, we launched our community Discord server. We previously had a section in Atom’s forum, but decided to have a more informal messaging platform to have a space for discussions between maintainers and Electron developers and for general debugging help.
• In 2021, we established the Electron China user group with the help of @BlackHole1. This group has been instrumental in Electron growth in users from China’s booming tech scene, providing a space for them to collaborate on ideas and discuss Electron outside of our English-language spaces. We’d also like to thank cnpm for their work in supporting Electron’s nightly releases in their Chinese mirror for npm.

Participating in high-visibility open source programs​

• We have been celebrating Hacktoberfest every year since 2019. Hacktoberfest is yearly celebration of open source organized by DigitalOcean, and we get dozens of enthusiastic contributors every year looking to make their mark on open source software.
• In 2020, we participated in the initial iteration of Google Season of Docs, where we worked with @bandantonio to rework Electron’s new user tutorial flow.
• In 2022, we mentored a Google Summer of Code student for the first time. @aryanshridhar did some awesome work to refactor Electron Fiddle's core version loading logic and migrate its bundler to webpack.

Automate all the things!​

Today, Electron governance has about 30 active maintainers. Less than half of us are full-time contributors, which means that there’s a lot of work to go around. What’s our trick to keeping everything running smoothly? Our motto is that computers are cheap, and human time is expensive. In typical engineer fashion, we’ve developed a suite of automated support tooling to make our lives easier.

Not Goma​

The core Electron codebase is a behemoth of C++ code, and build times have always been a limiting factor in how fast we can ship bug fixes and new features. In 2020, we deployed Not Goma, a custom Electron-specific backend for Google’s Goma distributed compiler service. Not Goma processes compilation requests from authorized user’s machines and distributes the process across hundreds of cores in the backend. It also caches the compilation result so that someone else compiling the same files will only need to download the pre-compiled result.

Since launching Not Goma, compilation times for maintainers have decreased from the scale of hours to minutes. A stable internet connection became the minimum requirement for contributors to compile Electron!

Continuous Factor Authentication​

Continuous Factor Authentication (CFA) is a layer of automation around npm’s two-factor authentication (2FA) system that we combine with semantic-release to manage secure and automated releases of our various @electron/ npm packages.

While semantic-release already automates the npm package publishing process, it requires turning off two-factor authentication or passing in a secret token that bypasses this restriction.

We built CFA to deliver a time-based one-time password (TOTP) for npm 2FA to arbitrary CI jobs, allowing us to harness the automation of semantic-release while keeping the additional security of two-factor authentication.

We use CFA with a Slack integration front-end, allowing maintainers to validate package publishing from any device they have Slack on, as long as they have their TOTP generator handy.

Sheriff​

Sheriff is an open source tool we wrote to automate the management of permissions across GitHub, Slack, and Google Workspace.

Sheriff’s key value proposition is that permission management should be a transparent process. It uses a single YAML config file that designates permissions across all the above listed services. With Sheriff, getting collaborator status on a repo or creating a new mailing list is as easy as getting a PR approved and merged.

Sheriff also has an audit log that posts to Slack, warning admins when suspicious activity occurs anywhere in the Electron organization.

…and all our GitHub bots​

GitHub is a platform with rich API extensibility and a first-party bot application framework called Probot. To help us focus on the more creative parts of our job, we built out a suite of smaller bots that help do the dirty work for us. Here are a few examples:

• Sudowoodo automates the Electron release process from start to finish, from kicking off builds to uploading the release assets to GitHub and npm.
• Trop automates the backporting process for Electron by attempting to cherry-pick patches to previous release branches based on GitHub PR labels.
• Roller automates rolling upgrades of Electron’s Chromium and Node.js dependencies.
• Cation is our status check bot for electron/electron PRs.

Altogether, our little family of bots has given us a huge boost in developer productivity!

What’s next?​

As we enter our second decade as a project, you might be asking: what’s next for Electron?

We’re going to stay in sync with Chromium's release cadence, releasing new major versions of Electron every 8 weeks, keeping the framework updated with the latest and greatest from the web platform and Node.js while maintaining stability and security for enterprise-grade applications.

We generally announce news on upcoming initiatives when they become concrete. If you want to keep up with future releases, features, and general project updates, you can read our blog and follow our social media profiles (Twitter and Mastodon)!

Electron 23.0.0 has been released! It includes upgrades to Chromium 110, V8 11.0, and Node.js 18.12.1. Additionally, support for Windows 7/8/8.1 has been dropped. Read below for more details!

The Electron team is excited to announce the release of Electron 23.0.0! You can install it with npm via npm install electron@latest or download it from our releases website. Continue reading for details about this release.

If you have any feedback, please share it with us on Twitter, or join our community Discord! Bugs and feature requests can be reported in Electron's issue tracker.

Notable Changes​

Stack Changes​

• Chromium 110
  • New in Chrome 110
  • New in Chrome 109
  • New in DevTools 110
  • New in DevTools 109
• Node.js 18.12.1
  • Node 18.12.1 blog post
• V8 11.0

New Features​

• Added label property to Display objects. #36933
• Added an app.getPreferredSystemLanguages() API to return the user's system languages. #36035
• Added support for the WebUSB API. #36289
• Added support for SerialPort.forget() as well as a new event serial-port-revoked emitted on Session objects when a given origin is revoked. #35310
• Added new win.setHiddenInMissionControl API to allow developers to opt out of Mission Control on macOS. #36092

Dropping Windows 7/8/8.1 Support​

Electron 23 no longer supports Windows 7/8/8.1. Electron follows the planned Chromium deprecation policy, which will deprecate Windows 7/8/8.1 , as well as Windows Server 2012 and 2012 R2 support in Chromium 109 (read more here).

Breaking API Changes​

Below are breaking changes introduced in Electron 23. You can read more about these changes and future changes on the Planned Breaking Changes page.

Removed: BrowserWindow scroll-touch-* events​

The deprecated scroll-touch-begin, scroll-touch-end and scroll-touch-edge events on BrowserWindow have been removed. Instead, use the newly available input-event event on WebContents.

// Removed in Electron 23.0
-win.on('scroll-touch-begin', scrollTouchBegin)
-win.on('scroll-touch-edge', scrollTouchEdge)
-win.on('scroll-touch-end', scrollTouchEnd)

// Replace with
+win.webContents.on('input-event', (_, event) => {
+  if (event.type === 'gestureScrollBegin') {
+    scrollTouchBegin()
+  } else if (event.type === 'gestureScrollUpdate') +{
+    scrollTouchEdge()
+  } else if (event.type === 'gestureScrollEnd') {
+    scrollTouchEnd()
+  }
+})

End of Support for 20.x.y​

Electron 20.x.y has reached end-of-support as per the project's support policy. Developers and applications are encouraged to upgrade to a newer version of Electron.

What's Next​

In the short term, you can expect the team to continue to focus on keeping up with the development of the major components that make up Electron, including Chromium, Node, and V8.

You can find Electron's public timeline here.

More information about future changes can be found on the Planned Breaking Changes page.

Electron 22.0.0 has been released! It includes a new utility process API, updates for Windows 7/8/8.1 support, and upgrades to Chromium 108, V8 10.8, and Node.js 16.17.1. Read below for more details!

The Electron team is excited to announce the release of Electron 22.0.0! You can install it with npm via npm install electron@latest or download it from our releases website. Continue reading for details about this release.

If you have any feedback, please share it with us on Twitter, or join our community Discord! Bugs and feature requests can be reported in Electron's issue tracker.

Notable Changes​

Stack Changes​

• Chromium 108
  • New in Chrome 108
  • New in Chrome 107
  • New in DevTools 108
  • New in DevTools 107
• Node.js 16.17.1
  • Node 16.17.1 blog post
• V8 10.8

Highlighted Features​

UtilityProcess API #36089​

The new UtilityProcess main process module allows the creation of a lightweight Chromium child process with only Node.js integration while also allowing communication with a sandboxed renderer using MessageChannel. The API was designed based on Node.js child_process.fork to allow for easier transition, with one primary difference being that the entry point modulePath must be from within the packaged application to allow only for trusted scripts to be loaded. Additionally the module prevents establishing communication channels with renderers by default, upholding the contract in which the main process is the only trusted process in the application.

You can read more about the new UtilityProcess API in our docs here.

Windows 7/8/8.1 Support Update​

Electron 22 will be the last Electron major version to support Windows 7/8/8.1. Electron follows the planned Chromium deprecation policy, which will deprecate Windows 7/8/8.1 support in Chromium 109 (read more here).

Windows 7/8/8.1 will not be supported in Electron 23 and later major releases.

Additional Highlighted Changes​

• Added support for Web Bluetooth pin pairing on Linux and Windows. #35416
• Added LoadBrowserProcessSpecificV8Snapshot as a new fuse that will let the main/browser process load its v8 snapshot from a file at browser_v8_context_snapshot.bin. Any other process will use the same path as is used today. #35266
• Added WebContents.opener to access window opener and webContents.fromFrame(frame) to get the WebContents corresponding to a WebFrameMain instance. #35140
• Added support for navigator.mediaDevices.getDisplayMedia via a new session handler, ses.setDisplayMediaRequestHandler. #30702

Breaking API Changes​

Below are breaking changes introduced in Electron 22. You can read more about these changes and future changes on the Planned Breaking Changes page.

Deprecated: webContents.incrementCapturerCount(stayHidden, stayAwake)​

webContents.incrementCapturerCount(stayHidden, stayAwake) has been deprecated. It is now automatically handled by webContents.capturePage when a page capture completes.

const w = new BrowserWindow({ show: false })

- w.webContents.incrementCapturerCount()
- w.capturePage().then(image => {
-   console.log(image.toDataURL())
-   w.webContents.decrementCapturerCount()
- })

+ w.capturePage().then(image => {
+   console.log(image.toDataURL())
+ })

Deprecated: webContents.decrementCapturerCount(stayHidden, stayAwake)​

webContents.decrementCapturerCount(stayHidden, stayAwake) has been deprecated. It is now automatically handled by webContents.capturePage when a page capture completes.

const w = new BrowserWindow({ show: false })

- w.webContents.incrementCapturerCount()
- w.capturePage().then(image => {
-   console.log(image.toDataURL())
-   w.webContents.decrementCapturerCount()
- })

+ w.capturePage().then(image => {
+   console.log(image.toDataURL())
+ })

Removed: WebContents new-window event​

The new-window event of WebContents has been removed. It is replaced by webContents.setWindowOpenHandler().

- webContents.on('new-window', (event) => {
-   event.preventDefault()
- })

+ webContents.setWindowOpenHandler((details) => {
+   return { action: 'deny' }
+ })

Deprecated: BrowserWindow scroll-touch-* events​

The scroll-touch-begin, scroll-touch-end and scroll-touch-edge events on BrowserWindow are deprecated. Instead, use the newly available input-event event on WebContents.

// Deprecated
- win.on('scroll-touch-begin', scrollTouchBegin)
- win.on('scroll-touch-edge', scrollTouchEdge)
- win.on('scroll-touch-end', scrollTouchEnd)

// Replace with
+ win.webContents.on('input-event', (_, event) => {
+   if (event.type === 'gestureScrollBegin') {
+     scrollTouchBegin()
+   } else if (event.type === 'gestureScrollUpdate') {
+     scrollTouchEdge()
+   } else if (event.type === 'gestureScrollEnd') {
+     scrollTouchEnd()
+   }
+ })

End of Support for 19.x.y​

Electron 19.x.y has reached end-of-support as per the project's support policy. Developers and applications are encouraged to upgrade to a newer version of Electron.

What's Next​

The Electron project will pause for the the month of December 2022, and return in January 2023. More information can be found in the December shutdown blog post.

In the short term, you can expect the team to continue to focus on keeping up with the development of the major components that make up Electron, including Chromium, Node, and V8.

You can find Electron's public timeline here.

More information about future changes can be found on the Planned Breaking Changes page.

Electron will end support of Windows 7, Windows 8 and Windows 8.1 beginning in Electron 23.

In line with Chromium’s deprecation policy, Electron will end support of Windows 7, Windows 8 and Windows 8.1 beginning in Electron 23. This matches Microsoft's end of support for Windows 7 ESU and Windows 8.1 extended on January 10th, 2023.

Electron 22 will be the last Electron major version to support Windows versions older than 10. Windows 7/8/8.1 will not be supported in Electron 23 and later major releases. Older versions of Electron will continue to function on Windows 7, and we will continue to release patches for Electron the 22.x series until May 30 2023, when Electron will end support for 22.x (according to our support timeline).

Why deprecate?​

Electron follows the planned Chromium deprecation policy, which will deprecate support in Chromium 109 (read more about Chromium's timeline here). Electron 23 will contain Chromium 110, which won’t support older versions of Windows.

Electron 22, which contains Chromium 108, will thus be the last supported version.

Deprecation timeline​

The following is our planned deprecation timeline:

• December 2022: The Electron team is entering a quiet period for the holidays
• January 2023: Windows 7 & 8 related issues are accepted for all supported release branches.
• February 7 2023: Electron 23 is released.
• February 8 2023 - May 29 2023: Electron will continue to accept fixes for supported lines older than Electron 23.
• May 30 2023: Electron 22 reaches the end of its support cycle.

What this means for developers:

• The Electron team will accept issues and fixes related to Windows 7/8/8.1 for stable supported lines, until each line reaches the end of its support cycle.
  • This specifically applies to Electron 22, Electron 21 and Electron 20.
• New issues related to Windows 7/8/8.1 will be accepted for Electron versions older than Electron 23.
  • New issues will not be accepted for any newer release lines.
• Once Electron 22 has reached the end of its support cycle, all existing issues related to Windows 7/8/8.1 will be closed.

What's next​

Please feel free to write to us at info@electronjs.org if you have any questions or concerns. You can also find community support in our official Electron Discord.

The Electron project will pause for the month of December 2022, then return to full speed in January 2023.

via GIPHY

What will be the same in December​

1. Zero-day and other major security-related releases will be published as necessary. Security incidents should be reported via SECURITY.md.
2. Code of Conduct reports and moderation will continue.

What will be different in December​

1. No new Stable releases in December. No Nightly and Alpha releases for the last two weeks of December.
2. With few exceptions, no pull request reviews or merges.
3. No issue tracker updates on any repositories.
4. No Discord debugging help from maintainers.
5. No social media content updates.

Why is this happening?​

With the success of December Quiet Month 2021, we wanted to bring it back for 2022. December continues to be a quiet month for most companies, so we want to give our maintainers a chance to recharge. Everyone is looking forward to 2023, and we expect good things to come! We encourage other projects to consider similar measures.

We are excited to announce that Electron Forge v6.0.0 is now available! This release marks the first major release of Forge since 2018 and moves the project from electron-userland into the main electron organization on Github.

Keep on reading to see what's new and how your app can adopt Electron Forge!

What is Electron Forge?​

Electron Forge is a tool for packaging and distributing Electron applications. It unifies Electron's build tooling ecosystem into a single extensible interface so that anyone can jump right into making Electron apps.

Highlight features include:

• 📦 Application packaging and code signing
• 🚚 Customizable installers on Windows, macOS, and Linux (DMG, deb, MSI, PKG, AppX, etc.)
• ☁️ Automated publishing flow for cloud providers (GitHub, S3, Bitbucket, etc.)
• ⚡️ Easy-to-use boilerplate templates for webpack and TypeScript
• ⚙️ Native Node.js module support
• 🔌 Extensible JavaScript plugin API

What's new in v6?​

Completely rewritten​

From v1 to v5, Electron Forge was based on the now-discontinued electron-compile project. Forge 6 is a complete rewrite of the project with a new modular architecture that can be extended to meet any Electron application's needs.

In the past few years, Forge v6.0.0-beta has achieved feature parity with v5 and code churn has slowed down dramatically, making the tool ready for general adoption.

Officially supported​

Historically, Electron maintainers have been unopinionated about build tooling, leaving the task to various community packages. However, with Electron maturing as a project, it has become harder for new Electron developers to understand which tools they need to build and distribute their apps.

To help guide Electron developers in the distribution process, we have have decided to make Forge the official batteries-included build pipeline for Electron.

Over the past year, we have been slowly integrating Forge into the official Electron documentation, and we have recently moved Forge over from its old home in electron-userland/electron-forge to the electron/forge repo. Now, we are finally ready to release Electron Forge to a general audience!

Getting started​

Initializing a new Forge project​

Scaffolding a new Electron Forge project can be done using the create-electron-app CLI script.

yarn create electron-app my-app --template=webpack
cd my-app
yarn start

npm init electron-app@latest my-app -- --template=webpack
cd my-app
npm start

The script will create an Electron project in the my-app folder with completely JavaScript bundling and a preconfigured build pipeline.

For more info, see the Getting Started guide in the Forge docs.

Importing an existing project​

The Electron Forge CLI also contains an import command for existing Electron projects.

cd my-app
yarn add --dev @electron-forge/cli
yarn electron-forge import

cd my-app
npm install --save-dev @electron-forge/cli
npm exec --package=@electron-forge/cli -c "electron-forge import"

When you use the import command, Electron Forge will add a few core dependencies and create a new forge.config.js configuration. If you have any existing build tooling (e.g. Electron Packager, Electron Builder, or Forge 5), it will try to migrate as many settings as possible. Some of your existing configuration may need to be migrated manually.

Manual migration details can be found in the Forge import documentation. If you need help, please stop by our Discord server!

Why switch to Forge?​

If you already have tooling for packaging and publishing your Electron app, the benefits associated with adopting Electron Forge can still outweigh the initial switching cost.

We believe there are two main benefits to using Forge:

1. Forge receives new features for application building as soon as they are supported in Electron. In this case, you won't need to wire in new tooling support yourself, or wait for that support to be eventually implemented by other packages before upgrading. For recent examples, see macOS universal binaries and ASAR integrity checking.

2. Forge's multi-package architecture makes it easy to understand and extend. Since Forge is made up of many smaller packages with clear responsibilities, it is easier to follow code flow. In addition, Forge's extensible API design means that you can write your own additional build logic separate from the provided configuration options for advanced use cases. For more details on writing custom Forge plugins, makers, and publishers, see the Extending Electron Forge section of the docs.

Breaking changes​

Forge 6 has spent a long time in the beta phase, and its release cadence has gradually slowed down. However, we have accelerated development in the second half of 2022 and used the last few releases to push some final breaking changes before the v6.0.0 stable release.

If you are an Electron Forge 6 beta user, see the v6.0.0 GitHub release notes for a list of breaking changes made in recent betas (>=6.0.0-beta.65).

A complete list of changes and commits can be found in the repo's CHANGELOG.md.

Submit your feedback!​

Tell us what you need! The Electron Forge team is always looking to build the project to better suit its users.

You can help us improve Electron Forge by submitting feature requests, posting issues, or just letting us know your feedback! You can also join us in the official Electron Discord server, where there is a dedicated channel for Electron Forge discussion.

If you want to give any feedback on the Forge docs at https://electronforge.io, we have a GitBook instance synced to the electron-forge/electron-forge-docs repo.

Last month, Electron’s maintainer group met up in Vancouver, Canada to discuss the direction of the project for 2023 and beyond. Over four days in a conference room, core maintainers and invited collaborators discussed new initiatives, maintenance pain points, and general project health.

Going forward, the team will still be fully dedicated to releasing regular and rapid Chromium upgrades, fixing bugs, and making Electron more secure and performant for everyone. We also have a few exciting projects in the works we would love to share with the community!

Transformative new APIs​

Major API proposals in the Electron project that require consensus go through a Request for Comments (RFC) process, which gets reviewed by members of our API Working Group.

This year, we have driven forward two major proposals that have the potential to unlock a new dimension of capabilities for Electron apps. These proposals are highly experimental, but here’s a sneak peek of what to expect!

New native addon enhancements (C APIs)​

This proposal outlines a new layer of Electron C APIs that will allow app developers to write their own Native Node Addons that interface with Electron’s internal resources, similar to Node’s own Node-API. More information about the proposed new API can be found here.

Example: Supercharging apps with Chromium resources​

Many Electron apps maintain their own forks to interact directly with Chromium internals that would otherwise be inaccessible with vanilla (unmodified) Electron. By exposing these resources in the C API layer, this code can instead live as a native module alongside Electron, potentially reducing app developer maintenance burden.

Exposing Chromium’s UI layer (Views API)​

Under the hood, the non-website parts of Chrome’s user interface (UI), such as toolbars, tabs, or buttons, are built with a framework called Views. The Views API proposal introduces parts of this framework as JavaScript classes in Electron, with the eventual goal of allowing developers to create non-web UI elements to their Electron applications. This will prevent apps from having to hack together web contents.

The groundwork to make this new set of APIs possible is currently in progress. Here are a few of the first things you can expect in the near future.

Example: Refactoring the window model with WebContentsView​

Our first planned change is to expose Chrome’s WebContentsView to Electron’s API surface, which will be the successor to our existing BrowserView API (which, despite the name, is Electron-specific code unrelated to Chromium Views). With WebContentsView exposed, we will have a reusable View object that can display web contents, opening the door to making the BrowserWindow class pure JavaScript and eliminating even more code complexity.

Although this change doesn’t provide a lot of new functionality to app developers, it is a large refactor that eliminates a lot of code under the hood, simplifying Chromium upgrades and reducing the risk of new bugs appearing between major versions.

If you’re an Electron developer using BrowserViews in your app: don’t worry, we haven’t forgotten about you! We plan on making the existing BrowserView class a shim for WebContentsView to provide a buffer as you transition to the newer APIs.

See: electron/electron#35658

Example: Scrollable web contents with ScrollView​

Our friends at Stack have been driving an initiative to expose the Chromium ScrollView component to Electron’s API. With this new API, any child View component can be made scrollable horizontally or vertically.

Although this new API fulfills a single smaller functionality, the team’s eventual goal is to build a set of utility View components that can be used as a toolkit to build more complex non-HTML interfaces.

Getting involved​

Are you an Electron app developer interested in either of these API proposals? Although we’re not quite ready to receive additional RFCs, please stay tuned for more details in the future!

Electron Forge v6 stable release​

Since the framework’s inception, Electron’s build tooling ecosystem has been largely community-driven and has consisted of many small single-purpose packages (e.g. electron-winstaller, electron-packager, electron-notarize, electron-osx-sign). Although these tools work well, it’s intimidating for users to piece together a working build pipeline.

To help build a friendlier experience for Electron developers, we built Electron Forge, an all-in-one solution that combines all this existing tooling into a single interface. Although Forge has been in development since 2017, the project has lain dormant for the last few years. However, given community feedback on the state of build tooling in Electron, we have been hard at work on releasing the next-gen stable major version of Forge.

Electron Forge 6 comes with first-class TypeScript and Webpack support, as well as an extensible API that allows developers to create their own plugins and installers.

Stay tuned: announcement coming soon​

If you’re interested in building a project with Forge or building templates or plugins with Forge’s extensible third-party APIs, stay tuned for our official announcement on the Forge v6 stable release sometime this month!

What’s next?​

Aside from the above, the team is always thinking of a bunch of exploratory projects to make the Electron experience better for app developers and end users. Updater tooling, API review processes, and enhanced documentation are other things we are experimenting with. We hope to have more news to share in the near future!

Electron 21.0.0 has been released! It includes upgrades to Chromium 106, V8 10.6, and Node.js 16.16.0. Read below for more details!

The Electron team is excited to announce the release of Electron 21.0.0! You can install it with npm via npm install electron@latest or download it from our releases website. Continue reading for details about this release.

If you have any feedback, please share it with us on Twitter, or join our community Discord! Bugs and feature requests can be reported in Electron's issue tracker.

Notable Changes​

Stack Changes​

• Chromium 106
  • New in Chrome 106
  • New in Chrome 105
  • New in DevTools 106
  • New in DevTools 105
• Node.js 16.16.0
  • Node 16.16.0 blog post
• V8 10.6

New Features​

• Added webFrameMain.origin. #35534
• Added new WebContents.ipc and WebFrameMain.ipc APIs. #35231
• Added support for panel-like behavior. Window can float over full-screened apps. #34388
• Added support for push notifications from APNs for macOS apps. #33574

Breaking & API Changes​

Below are breaking changes introduced in Electron 21.

V8 Memory Cage Enabled​

Electron 21 enables V8 sandboxed pointers, following Chrome's decision to do the same in Chrome 103. This has some implications for native modules. This feature has performance and security benefits, but also places some new restrictions on native modules, e.g. use of ArrayBuffers that point to external ("off-heap") memory. Please see this blog post for more information. #34724

Refactored webContents.printToPDF​

Refactored webContents.printToPDF to align with Chromium's headless implementation. See #33654 for more information.

More information about these and future changes can be found on the Planned Breaking Changes page.

End of Support for 18.x.y​

Electron 18.x.y has reached end-of-support as per the project's support policy. Developers and applications are encouraged to upgrade to a newer version of Electron.

What's Next​

In the short term, you can expect the team to continue to focus on keeping up with the development of the major components that make up Electron, including Chromium, Node, and V8.

You can find Electron's public timeline here.

More information about future changes can be found on the Planned Breaking Changes page.

Electron 20.0.0 has been released! It includes upgrades to Chromium 104, V8 10.4, and Node.js 16.15.0. Read below for more details!

The Electron team is excited to announce the release of Electron 20.0.0! You can install it with npm via npm install electron@latest or download it from our releases website. Continue reading for details about this release and please share any feedback you have!

Notable Changes​

New Features​

• Added immersive dark mode on Windows. #34549
• Added support for panel-like behavior. Window can float over full-screened apps. #34665
• Updated Windows Control Overlay buttons to look and feel more native on Windows 11. #34888
• Renderers are now sandboxed by default unless nodeIntegration: true or sandbox: false is specified. #35125
• Added safeguards when building native modules with nan. #35160

Stack Changes​

• Chromium 104
  • New in Chrome 104
  • New in Chrome 103
  • New in DevTools
• Node.js 16.15.0
  • Node 16.15.0 blog post
• V8 10.4

Breaking & API Changes​

Below are breaking changes introduced in Electron 20. More information about these and future changes can be found on the Planned Breaking Changes page.

Default Changed: renderers without nodeIntegration: true are sandboxed by default​

Previously, renderers that specified a preload script defaulted to being unsandboxed. This meant that by default, preload scripts had access to Node.js. In Electron 20, this default has changed. Beginning in Electron 20, renderers will be sandboxed by default, unless nodeIntegration: true or sandbox: false is specified.

If your preload scripts do not depend on Node, no action is needed. If your preload scripts do depend on Node, either refactor them to remove Node usage from the renderer, or explicitly specify sandbox: false for the relevant renderers.

Fixed: spontaneous crashing in nan native modules​

In Electron 20, we changed two items related to native modules:

1. V8 headers now use c++17 by default. This flag was added to electron-rebuild.
2. We fixed an issue where a missing include would cause spontaneous crashing in native modules that depended on nan.

For the most stability, we recommend using node-gyp >=8.4.0 and electron-rebuild >=3.2.9 when rebuilding native modules, particularly modules that depend on nan. See electron #35160 and node-gyp #2497 for more information.

Removed: .skipTaskbar on Linux​

On X11, skipTaskbar sends a _NET_WM_STATE_SKIP_TASKBAR message to the X11 window manager. There is not a direct equivalent for Wayland, and the known workarounds have unacceptable tradeoffs (e.g. Window.is_skip_taskbar in GNOME requires unsafe mode), so Electron is unable to support this feature on Linux.

End of Support for 17.x.y​

Electron 17.x.y has reached end-of-support as per the project's support policy. Developers and applications are encouraged to upgrade to a newer version of Electron.

What's Next​

In the short term, you can expect the team to continue to focus on keeping up with the development of the major components that make up Electron, including Chromium, Node, and V8. Although we are careful not to make promises about release dates, our plan is to release new major versions of Electron with new versions of those components approximately every 2 months.

You can find Electron's public timeline here.

More information about future changes can be found on the Planned Breaking Changes page.

Electron 21 and later will have the V8 Memory Cage enabled, with implications for some native modules.

In Electron 21, we will be enabling V8 sandboxed pointers in Electron, following Chrome's decision to do the same in Chrome 103. This has some implications for native modules. Also, we previously enabled a related technology, pointer compression, in Electron 14. We didn't talk about it much then, but pointer compression has implications for the maximum V8 heap size.

These two technologies, when enabled, are significantly beneficial for security, performance and memory usage. However, there are some downsides to enabling them, too.

The main downside of enabling sandboxed pointers is that ArrayBuffers which point to external ("off-heap") memory are no longer allowed. This means that native modules which rely on this functionality in V8 will need to be refactored to continue working in Electron 20 and later.

The main downside of enabling pointer compression is that the V8 heap is limited to a maximum size of 4GB. The exact details of this are a little complicated—for example, ArrayBuffers are counted separately from the rest of the V8 heap, but have their own limits.

The Electron Upgrades Working Group believes that the benefits of pointer compression and the V8 memory cage outweigh the downsides. There are three main reasons for doing so:

1. It keeps Electron closer to Chromium. The less Electron diverges from Chromium in complex internal details such as V8 configuration, the less likely we are to accidentally introduce bugs or security vulnerabilities. Chromium's security team is formidable, and we want to make sure we are taking advantage of their work. Further, if a bug only affects configurations that aren't used in Chromium, fixing it is not likely to be a priority for the Chromium team.
2. It performs better. Pointer compression reduces V8 heap size by up to 40% and improves CPU and GC performance by 5%–10%. For the vast majority of Electron applications which won't bump into the 4GB heap size limit and don't use native modules that require external buffers, these are significant performance wins.
3. It's more secure. Some Electron apps run untrusted JavaScript (hopefully following our security recommendations!), and for those apps, having the V8 memory cage enabled protects them from a large class of nasty V8 vulnerabilities.

Lastly, there are workarounds for apps that really need a larger heap size. For example, it is possible to include a copy of Node.js with your app, which is built with pointer compression disabled, and move the memory-intensive work to a child process. Though somewhat complicated, it is also possible to build a custom version of Electron with pointer compression disabled, if you decide you want a different trade-off for your particular use case. And lastly, in the not-too-distant future, wasm64 will allow apps built with WebAssembly both on the Web and in Electron to use significantly more than 4GB of memory.

FAQ​

How will I know if my app is impacted by this change?​

Attempting to wrap external memory with an ArrayBuffer will crash at runtime in Electron 20+.

If you don't use any native Node modules in your app, you're safe—there's no way to trigger this crash from pure JS. This change only affects native Node modules which allocate memory outside of the V8 heap (e.g. using malloc or new) and then wrap the external memory with an ArrayBuffer. This is a fairly rare use case, but some modules do use this technique, and such modules will need to be refactored in order to be compatible with Electron 20+.

How can I measure how much V8 heap memory my app is using to know if I'm close to the 4GB limit?​

In the renderer process, you can use performance.memory.usedJSHeapSize, which will return the V8 heap usage in bytes. In the main process, you can use process.memoryUsage().heapUsed, which is comparable.

What is the V8 memory cage?​

Some documents refer to it as the "V8 sandbox", but that term is easily confusable with other kinds of sandboxing that happen in Chromium, so I'll stick to the term "memory cage".

There's a fairly common kind of V8 exploit that goes something like this:

1. Find a bug in V8's JIT engine. JIT engines analyze code in order to be able to omit slow runtime type checks and produce fast machine code. Sometimes logic errors mean it gets this analysis wrong, and omits a type check that it actually needed—say, it thinks x is a string, but in fact it's an object.
2. Abuse this confusion to overwrite some bit of memory inside the V8 heap, for instance, the pointer to the beginning of an ArrayBuffer.
3. Now you have an ArrayBuffer that points wherever you like, so you can read and write any memory in the process, even memory that V8 normally doesn't have access to.

The V8 memory cage is a technique designed to categorically prevent this kind of attack. The way this is accomplished is by not storing any pointers in the V8 heap. Instead, all references to other memory inside the V8 heap are stored as offsets from the beginning of some reserved region. Then, even if an attacker manages to corrupt the base address of an ArrayBuffer, for instance by exploiting a type confusion error in V8, the worst they can do is read and write memory inside the cage, which they could likely already do anyway. There's a lot more available to read on how the V8 memory cage works, so I won't go into further detail here—the best place to start reading is probably the high-level design doc from the Chromium team.

I want to refactor a Node native module to support Electron 21+. How do I do that?​

There are two ways to go about refactoring a native module to be compatible with the V8 memory cage. The first is to copy externally-created buffers into the V8 memory cage before passing them to JavaScript. This is generally a simple refactor, but it can be slow when the buffers are large. The other approach is to use V8's memory allocator to allocate memory which you intend to eventually pass to JavaScript. This is a bit more involved, but will allow you to avoid the copy, meaning better performance for large buffers.

To make this more concrete, here's an example N-API module that uses external array buffers:

// Create some externally-allocated buffer.
// |create_external_resource| allocates memory via malloc().
size_t length = 0;
void* data = create_external_resource(&length);
// Wrap it in a Buffer--will fail if the memory cage is enabled!
napi_value result;
napi_create_external_buffer(
    env, length, data,
    finalize_external_resource, NULL, &result);

This will crash when the memory cage is enabled, because data is allocated outside the cage. Refactoring to instead copy the data into the cage, we get:

size_t length = 0;
void* data = create_external_resource(&length);
// Create a new Buffer by copying the data into V8-allocated memory
napi_value result;
void* copied_data = NULL;
napi_create_buffer_copy(env, length, data, &copied_data, &result);
// If you need to access the new copy, |copied_data| is a pointer
// to it!

This will copy the data into a newly-allocated memory region that is inside the V8 memory cage. Optionally, N-API can also provide a pointer to the newly-copied data, in case you need to modify or reference it after the fact.

Refactoring to use V8's memory allocator is a little more complicated, because it requires modifying the create_external_resource function to use memory allocated by V8, instead of using malloc. This may be more or less feasible, depending on whether or not you control the definition of create_external_resource. The idea is to first create the buffer using V8, e.g. with napi_create_buffer, and then initialize the resource into the memory that has been allocated by V8. It is important to retain a napi_ref to the Buffer object for the lifetime of the resource, otherwise V8 may garbage-collect the Buffer and potentially result in use-after-free errors.