Breaking Changes
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.
Types of Breaking Changes
This document uses the following convention to categorize breaking changes:
- API Changed: An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.
- Behavior Changed: The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown.
- Default Changed: Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value.
- Deprecated: An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
- Removed: An API or feature was removed, and is no longer supported by Electron.
Planned Breaking API Changes (31.0)
Removed: WebSQL
support
Chromium has removed support for WebSQL upstream, transitioning it to Android only. See Chromium's intent to remove discussion for more information.
Behavior Changed: nativeImage.toDataURL
will preseve PNG colorspace
PNG decoder implementation has been changed to preserve colorspace data, the encoded data returned from this function now matches it.
See crbug.com/332584706 for more information.
Behavior Changed: window.flashFrame(bool)
will flash dock icon continuously on macOS
This brings the behavior to parity with Windows and Linux. Prior behavior: The first flashFrame(true)
bounces the dock icon only once (using the NSInformationalRequest level) and flashFrame(false)
does nothing. New behavior: Flash continuously until flashFrame(false)
is called. This uses the NSCriticalRequest level instead. To explicitly use NSInformationalRequest
to cause a single dock icon bounce, it is still possible to use dock.bounce('informational')
.
Planned Breaking API Changes (30.0)
Behavior Changed: cross-origin iframes now use Permission Policy to access features
Cross-origin iframes must now specify features available to a given iframe
via the allow
attribute in order to access them.
See documentation for more information.
Removed: The --disable-color-correct-rendering
switch
This switch was never formally documented but it's removal is being noted here regardless. Chromium itself now has better support for color spaces so this flag should not be needed.
Behavior Changed: BrowserView.setAutoResize
behavior on macOS
In Electron 30, BrowserView is now a wrapper around the new WebContentsView API.
Previously, the setAutoResize
function of the BrowserView
API was backed by autoresizing on macOS, and by a custom algorithm on Windows and Linux.
For simple use cases such as making a BrowserView fill the entire window, the behavior of these two approaches was identical.
However, in more advanced cases, BrowserViews would be autoresized differently on macOS than they would be on other platforms, as the custom resizing algorithm for Windows and Linux did not perfectly match the behavior of macOS's autoresizing API.
The autoresizing behavior is now standardized across all platforms.
If your app uses BrowserView.setAutoResize
to do anything more complex than making a BrowserView fill the entire window, it's likely you already had custom logic in place to handle this difference in behavior on macOS.
If so, that logic will no longer be needed in Electron 30 as autoresizing behavior is consistent.
Removed: params.inputFormType
property on context-menu
on WebContents
The inputFormType
property of the params object in the context-menu
event from WebContents
has been removed. Use the new formControlType
property instead.
Removed: process.getIOCounters()
Chromium has removed access to this information.
Planned Breaking API Changes (29.0)
Behavior Changed: ipcRenderer
can no longer be sent over the contextBridge
Attempting to send the entire ipcRenderer
module as an object over the contextBridge
will now result in
an empty object on the receiving side of the bridge. This change was made to remove / mitigate
a security footgun. You should not directly expose ipcRenderer or its methods over the bridge.
Instead, provide a safe wrapper like below:
contextBridge.exposeInMainWorld('app', {
onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
Removed: renderer-process-crashed
event on app
The renderer-process-crashed
event on app
has been removed.
Use the new render-process-gone
event instead.
// Removed
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
Removed: crashed
event on WebContents
and <webview>
The crashed
events on WebContents
and <webview>
have been removed.
Use the new render-process-gone
event instead.
// Removed
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })
// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
Removed: gpu-process-crashed
event on app
The gpu-process-crashed
event on app
has been removed.
Use the new child-process-gone
event instead.
// Removed
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
Planned Breaking API Changes (28.0)
Behavior Changed: WebContents.backgroundThrottling
set to false affects all WebContents
in the host BrowserWindow
WebContents.backgroundThrottling
set to false will disable frames throttling
in the BrowserWindow
for all WebContents
displayed by it.
Removed: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position)
has been removed, the
BrowserWindow.setWindowButtonPosition(position)
API should be used instead
which accepts null
instead of { x: 0, y: 0 }
to reset the position to
system default.
// Removed in Electron 28
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })
// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)
Removed: BrowserWindow.getTrafficLightPosition()
BrowserWindow.getTrafficLightPosition()
has been removed, the
BrowserWindow.getWindowButtonPosition()
API should be used instead
which returns null
instead of { x: 0, y: 0 }
when there is no custom
position.
// Removed in Electron 28
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
// No custom position.
}
Removed: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been removed. It should be replaced by setting up a MessageChannel
between the renderers.
The senderId
and senderIsMainFrame
properties of IpcRendererEvent
have been removed as well.
Removed: app.runningUnderRosettaTranslation
The app.runningUnderRosettaTranslation
property has been removed.
Use app.runningUnderARM64Translation
instead.
// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
Deprecated: renderer-process-crashed
event on app
The renderer-process-crashed
event on app
has been deprecated.
Use the new render-process-gone
event instead.
// Deprecated
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
Deprecated: params.inputFormType
property on context-menu
on WebContents
The inputFormType
property of the params object in the context-menu
event from WebContents
has been deprecated. Use the new formControlType
property instead.
Deprecated: crashed
event on WebContents
and <webview>
The crashed
events on WebContents
and <webview>
have been deprecated.
Use the new render-process-gone
event instead.
// Deprecated
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })
// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
Deprecated: gpu-process-crashed
event on app
The gpu-process-crashed
event on app
has been deprecated.
Use the new child-process-gone
event instead.
// Deprecated
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
Planned Breaking API Changes (27.0)
Removed: macOS 10.13 / 10.14 support
macOS 10.13 (High Sierra) and macOS 10.14 (Mojave) are no longer supported by Chromium.
Older versions of Electron will continue to run on these operating systems, but macOS 10.15 (Catalina) or later will be required to run Electron v27.0.0 and higher.
Deprecated: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been deprecated. It should be replaced by setting up a MessageChannel
between the renderers.
The senderId
and senderIsMainFrame
properties of IpcRendererEvent
have been deprecated as well.
Removed: color scheme events in systemPreferences
The following systemPreferences
events have been removed:
inverted-color-scheme-changed
high-contrast-color-scheme-changed
Use the new updated
event on the nativeTheme
module instead.
// Removed
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replace with
nativeTheme.on('updated', () => { /* ... */ })
Removed: Some window.setVibrancy
options on macOS
The following vibrancy options have been removed:
- 'light'
- 'medium-light'
- 'dark'
- 'ultra-dark'
- 'appearance-based'
These were previously deprecated and have been removed by Apple in 10.15.
Removed: webContents.getPrinters
The webContents.getPrinters
method has been removed. Use
webContents.getPrintersAsync
instead.
const w = new BrowserWindow({ show: false })
// Removed
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
Removed: systemPreferences.{get,set}AppLevelAppearance
and systemPreferences.appLevelAppearance
The systemPreferences.getAppLevelAppearance
and systemPreferences.setAppLevelAppearance
methods have been removed, as well as the systemPreferences.appLevelAppearance
property.
Use the nativeTheme
module instead.
// Removed
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
Removed: alternate-selected-control-text
value for systemPreferences.getColor
The alternate-selected-control-text
value for systemPreferences.getColor
has been removed. Use selected-content-background
instead.
// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
Planned Breaking API Changes (26.0)
Deprecated: webContents.getPrinters
The webContents.getPrinters
method has been deprecated. Use
webContents.getPrintersAsync
instead.
const w = new BrowserWindow({ show: false })
// Deprecated
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
Deprecated: systemPreferences.{get,set}AppLevelAppearance
and systemPreferences.appLevelAppearance
The systemPreferences.getAppLevelAppearance
and systemPreferences.setAppLevelAppearance
methods have been deprecated, as well as the systemPreferences.appLevelAppearance
property.
Use the nativeTheme
module instead.
// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
Deprecated: alternate-selected-control-text
value for systemPreferences.getColor
The alternate-selected-control-text
value for systemPreferences.getColor
has been deprecated. Use selected-content-background
instead.
// Deprecated
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
Planned Breaking API Changes (25.0)
Deprecated: protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol
The protocol.register*Protocol
and protocol.intercept*Protocol
methods have
been replaced with protocol.handle
.
The new method can either register a new protocol or intercept an existing protocol, and responses can be of any type.
// Deprecated in Electron 25
protocol.registerBufferProtocol('some-protocol', () => {
callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})
// Replace with
protocol.handle('some-protocol', () => {
return new Response(
Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
{ headers: { 'content-type': 'text/html' } }
)
})
// Deprecated in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
callback({ url: 'https://electronjs.org' })
})
// Replace with
protocol.handle('some-protocol', () => {
return net.fetch('https://electronjs.org')
})
// Deprecated in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
callback({ filePath: '/path/to/my/file' })
})
// Replace with
protocol.handle('some-protocol', () => {
return net.fetch('file:///path/to/my/file')
})
Deprecated: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position)
has been deprecated, the
BrowserWindow.setWindowButtonPosition(position)
API should be used instead
which accepts null
instead of { x: 0, y: 0 }
to reset the position to
system default.
// Deprecated in Electron 25
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })
// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)
Deprecated: BrowserWindow.getTrafficLightPosition()
BrowserWindow.getTrafficLightPosition()
has been deprecated, the
BrowserWindow.getWindowButtonPosition()
API should be used instead
which returns null
instead of { x: 0, y: 0 }
when there is no custom
position.
// Deprecated in Electron 25
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
// No custom position.
}
Planned Breaking API Changes (24.0)
API Changed: nativeImage.createThumbnailFromPath(path, size)
The maxSize
parameter has been changed to size
to reflect that the size passed in will be the size the thumbnail created. Previously, Windows would not scale the image up if it were smaller than maxSize
, and
macOS would always set the size to maxSize
. Behavior is now the same across platforms.
Updated Behavior:
// a 128x128 image.
const imagePath = path.join('path', 'to', 'capybara.png')
// Scaling up a smaller image.
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
console.log(result.getSize()) // { width: 256, height: 256 }
})
// Scaling down a larger image.
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
console.log(result.getSize()) // { width: 64, height: 64 }
})
Previous Behavior (on Windows):
// a 128x128 image
const imagePath = path.join('path', 'to', 'capybara.png')
const size = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, size).then(result => {
console.log(result.getSize()) // { width: 128, height: 128 }
})
Planned Breaking API Changes (23.0)
Behavior Changed: Draggable Regions on macOS
The implementation of draggable regions (using the CSS property -webkit-app-region: drag
) has changed on macOS to bring it in line with Windows and Linux. Previously, when a region with -webkit-app-region: no-drag
overlapped a region with -webkit-app-region: drag
, the no-drag
region would always take precedence on macOS, regardless of CSS layering. That is, if a drag
region was above a no-drag
region, it would be ignored. Beginning in Electron 23, a drag
region on top of a no-drag
region will correctly cause the region to be draggable.
Additionally, the customButtonsOnHover
BrowserWindow property previously created a draggable region which ignored the -webkit-app-region
CSS property. This has now been fixed (see #37210 for discussion).
As a result, if your app uses a frameless window with draggable regions on macOS, the regions which are draggable in your app may change in Electron 23.
Removed: Windows 7 / 8 / 8.1 support
Windows 7, Windows 8, and Windows 8.1 are no longer supported. Electron follows the planned Chromium deprecation policy, which will deprecate Windows 7 support beginning in Chromium 109.
Older versions of Electron will continue to run on these operating systems, but Windows 10 or later will be required to run Electron v23.0.0 and higher.
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()
}
})
Removed: webContents.incrementCapturerCount(stayHidden, stayAwake)
The webContents.incrementCapturerCount(stayHidden, stayAwake)
function has been removed.
It is now automatically handled by webContents.capturePage
when a page capture completes.
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
Removed: webContents.decrementCapturerCount(stayHidden, stayAwake)
The webContents.decrementCapturerCount(stayHidden, stayAwake)
function has been removed.
It is now automatically handled by webContents.capturePage
when a page capture completes.
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
Planned Breaking API Changes (22.0)
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 })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
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 })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
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()
.
// Removed in Electron 22
webContents.on('new-window', (event) => {
event.preventDefault()
})
// Replace with
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})
Removed: <webview>
new-window
event
The new-window
event of <webview>
has been removed. There is no direct replacement.
// Removed in Electron 22
webview.addEventListener('new-window', (event) => {})
// Replace with
// main.js
mainWindow.webContents.on('did-attach-webview', (event, wc) => {
wc.setWindowOpenHandler((details) => {
mainWindow.webContents.send('webview-new-window', wc.id, details)
return { action: 'deny' }
})
})
// preload.js
const { ipcRenderer } = require('electron')
ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
console.log('webview-new-window', webContentsId, details)
document.getElementById('webview').dispatchEvent(new Event('new-window'))
})
// renderer.js
document.getElementById('webview').addEventListener('new-window', () => {
console.log('got new-window event')
})
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()
}
})
Planned Breaking API Changes (21.0)
Behavior Changed: V8 Memory Cage enabled
The V8 memory cage has been enabled, which has implications for native modules
which wrap non-V8 memory with ArrayBuffer
or Buffer
. See the
blog post about the V8 memory cage for
more details.
API Changed: webContents.printToPDF()
webContents.printToPDF()
has been modified to conform to Page.printToPDF
in the Chrome DevTools Protocol. This has been changes in order to
address changes upstream that made our previous implementation untenable and rife with bugs.
Arguments Changed
pageRanges
Arguments Removed
printSelectionOnly
marginsType
headerFooter
scaleFactor
Arguments Added
headerTemplate
footerTemplate
displayHeaderFooter
margins
scale
preferCSSPageSize
// Main process
const { webContents } = require('electron')
webContents.printToPDF({
landscape: true,
displayHeaderFooter: true,
printBackground: true,
scale: 2,
pageSize: 'Ledger',
margins: {
top: 2,
bottom: 2,
left: 2,
right: 2
},
pageRanges: '1-5, 8, 11-13',
headerTemplate: '<h1>Title</h1>',
footerTemplate: '<div><span class="pageNumber"></span></div>',
preferCSSPageSize: true
}).then(data => {
fs.writeFile(pdfPath, data, (error) => {
if (error) throw error
console.log(`Wrote PDF successfully to ${pdfPath}`)
})
}).catch(error => {
console.log(`Failed to write PDF to ${pdfPath}: `, error)
})