2018-05-29 09:15:30 +00:00
# API Contract
2018-06-22 03:43:39 +00:00
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least [one major version ](../tutorial/electron-versioning.md#semver ) before the change is made.
2018-05-29 09:15:30 +00:00
# `FIXME` comments
The `FIXME` string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme
2018-05-29 09:17:26 +00:00
# Planned Breaking API Changes (4.0)
2018-05-29 09:42:20 +00:00
The following list includes the breaking API changes planned for Electron 4.0.
2018-05-29 09:17:26 +00:00
## `app.makeSingleInstance`
```js
// Deprecated
app.makeSingleInstance(function (argv, cwd) {
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', function (argv, cwd) {
})
```
## `app.releaseSingleInstance`
```js
// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()
```
2018-06-27 06:47:01 +00:00
# Breaking API Changes (3.0)
2016-09-07 18:41:54 +00:00
2018-06-27 06:47:01 +00:00
The following list includes the breaking API changes in Electron 3.0.
2016-09-07 18:41:54 +00:00
2017-05-18 03:01:06 +00:00
## `app`
```js
// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()
2018-06-27 06:47:01 +00:00
// Deprecated
const metrics = app.getAppMetrics()
const {memory} = metrics[0]
memory.privateBytes // Deprecated property
memory.sharedBytes // Deprecated property
2017-05-18 03:01:06 +00:00
```
2016-09-08 16:09:49 +00:00
## `BrowserWindow`
```js
// Deprecated
2016-09-08 16:15:05 +00:00
let optionsA = {webPreferences: {blinkFeatures: ''}}
let windowA = new BrowserWindow(optionsA)
2016-09-08 16:09:49 +00:00
// Replace with
2016-09-08 16:15:05 +00:00
let optionsB = {webPreferences: {enableBlinkFeatures: ''}}
let windowB = new BrowserWindow(optionsB)
2018-05-21 01:52:04 +00:00
// Deprecated
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// do something
}
})
// Replace with
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// do something
}
})
2016-09-08 16:09:49 +00:00
```
## `clipboard`
2016-09-07 18:41:54 +00:00
```js
// Deprecated
clipboard.readRtf()
// Replace with
clipboard.readRTF()
// Deprecated
clipboard.writeRtf()
// Replace with
clipboard.writeRTF()
// Deprecated
clipboard.readHtml()
// Replace with
clipboard.readHTML()
// Deprecated
clipboard.writeHtml()
// Replace with
clipboard.writeHTML()
2016-09-08 16:09:49 +00:00
```
2016-11-28 23:06:03 +00:00
## `crashReporter`
```js
// Deprecated
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// Replace with
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})
```
2016-09-08 16:09:49 +00:00
## `nativeImage`
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
```js
2016-12-14 18:12:37 +00:00
// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})
2016-09-08 16:09:49 +00:00
```
2016-09-07 18:41:54 +00:00
2018-06-27 06:47:01 +00:00
## `process`
```js
// Deprecated
const info = process.getProcessMemoryInfo()
const privateBytes = info.privateBytes // deprecated property
const sharedBytes = info.sharedBytes // deprecated property
```
2018-03-07 07:06:33 +00:00
## `screen`
2016-09-16 22:57:07 +00:00
```js
// Deprecated
2018-03-07 07:06:33 +00:00
screen.getMenuBarHeight()
2016-09-16 22:57:07 +00:00
// Replace with
2018-03-07 07:06:33 +00:00
screen.getPrimaryDisplay().workArea
2016-09-16 22:57:07 +00:00
```
2017-02-07 23:44:56 +00:00
## `session`
```js
// Deprecated
ses.setCertificateVerifyProc(function (hostname, certificate, callback) {
callback(true)
})
// Replace with
2017-02-08 00:35:37 +00:00
ses.setCertificateVerifyProc(function (request, callback) {
2017-02-07 23:44:56 +00:00
callback(0)
})
```
2016-09-08 16:09:49 +00:00
## `Tray`
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
```js
2016-09-07 18:41:54 +00:00
// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')
// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')
2016-09-08 16:09:49 +00:00
```
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
## `webContents`
```js
2016-09-07 18:41:54 +00:00
// Deprecated
webContents.openDevTools({detach: true})
// Replace with
webContents.openDevTools({mode: 'detach'})
2018-08-23 01:45:43 +00:00
// Removed
webContents.setSize(options)
// There is no replacement for this API
2016-09-07 18:41:54 +00:00
```
2016-11-04 21:30:14 +00:00
2016-11-22 16:11:14 +00:00
## `webFrame`
```js
2016-11-14 18:33:30 +00:00
// Deprecated
webFrame.registerURLSchemeAsSecure('app')
// Replace with
2016-11-16 14:41:06 +00:00
protocol.registerStandardSchemes(['app'], {secure: true})
2016-11-14 18:33:30 +00:00
// Deprecated
webFrame.registerURLSchemeAsPrivileged('app', {secure: true})
// Replace with
2016-11-16 14:41:06 +00:00
protocol.registerStandardSchemes(['app'], {secure: true})
2016-11-22 16:11:14 +00:00
```
2018-08-23 01:45:43 +00:00
## `<webview>`
```js
// Removed
webview.setAttribute('disableguestresize', '')
// There is no replacement for this API
// Removed
webview.setAttribute('guestinstance', instanceId)
// There is no replacement for this API
```
2016-11-04 21:30:14 +00:00
## Node Headers URL
This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url`
command line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
Replace with: https://atom.io/download/electron
2017-06-15 19:46:25 +00:00
2018-05-29 09:23:28 +00:00
# Breaking API Changes (2.0)
2018-05-29 09:42:20 +00:00
The following list includes the breaking API changes made in Electron 2.0.
2018-05-29 09:23:28 +00:00
## `BrowserWindow`
```js
// Deprecated
let optionsA = {titleBarStyle: 'hidden-inset'}
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = {titleBarStyle: 'hiddenInset'}
let windowB = new BrowserWindow(optionsB)
```
## `menu`
```js
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
menu.popup(browserWindow, 100, 200, 2)
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
menu.popup(browserWindow, {x: 100, y: 200, positioningItem: 2})
```
2018-05-29 09:24:39 +00:00
## `nativeImage`
2018-05-29 09:23:28 +00:00
```js
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
nativeImage.toPng()
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
nativeImage.toPNG()
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
nativeImage.toJpeg()
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
nativeImage.toJPEG()
```
## `process`
* `process.versions.electron` and `process.version.chrome` will be made
read-only properties for consistency with the other `process.versions`
properties set by Node.
## `webContents`
```js
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
webContents.setZoomLevelLimits(1, 2)
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
webContents.setVisualZoomLevelLimits(1, 2)
```
## `webFrame`
```js
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
webFrame.setZoomLevelLimits(1, 2)
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
webFrame.setVisualZoomLevelLimits(1, 2)
```
## `<webview>`
```js
2018-05-29 09:37:42 +00:00
// Removed
2018-05-29 09:23:28 +00:00
webview.setZoomLevelLimits(1, 2)
2018-05-29 09:37:42 +00:00
// Replaced with
2018-05-29 09:23:28 +00:00
webview.setVisualZoomLevelLimits(1, 2)
```
## Duplicate ARM Assets
2018-05-29 09:37:42 +00:00
Each Electron release includes two identical ARM builds with slightly different
filenames, like `electron-v1.7.3-linux-arm.zip` and
`electron-v1.7.3-linux-armv7l.zip` . The asset with the `v7l` prefix was added
to clarify to users which ARM version it supports, and to disambiguate it from
2018-05-29 09:23:28 +00:00
future armv6l and arm64 assets that may be produced.
2018-05-29 09:37:42 +00:00
The file _without the prefix_ is still being published to avoid breaking any
setups that may be consuming it. Starting at 2.0, the un-prefixed file will
2018-05-29 09:23:28 +00:00
no longer be published.
For details, see
[6986 ](https://github.com/electron/electron/pull/6986 )
2018-05-29 09:37:42 +00:00
and
2018-05-29 09:23:28 +00:00
[7189 ](https://github.com/electron/electron/pull/7189 ).