refactor: use GetDefaultStoragePartition()
Use GetDefaultStorageParition() instead of GetStoragePartition(nullptr)
- It improves code uniformity, since we use get-default everywhere else
- It's more readable
- It's marginally faster, since GetStoragePartition() has more steps
Added in 49b0a1bf4a
refactor: remove unused ElectronBrowserContext::extension_system()
Last use removed on Jul 21, 2020 by 2fb14f5 in PR #24575
This fixes a raw_ptr warning by letting us remove the raw_ptr field
`ElectronBrowserContext::extension_system_`.
* refactor: make UtilityProcessWrapper inherit privately from mojo::MessageReceiver
* refactor: make ParentPort inherit privately from mojo::MessageReceiver
* refactor: make MessagePort inherit privately from mojo::MessageReceiver
* chore: bump chromium in DEPS to 136.0.7059.0
* chore: bump chromium in DEPS to 136.0.7060.0
* chore: bump chromium in DEPS to 136.0.7062.0
---------
Co-authored-by: electron-roller[bot] <84116207+electron-roller[bot]@users.noreply.github.com>
* perf: use base::SplitStringPiece() in SetNodeOptions()
* perf: use base::SplitStringPiece() in StringToAccelerator()
* refactor: StringToAccelerator() now takes a std::string_view
* chore: bump chromium in DEPS to 136.0.7054.0
* chore: update allow_in-process_windows_to_have_different_web_prefs.patch
Xref: https://chromium-review.googlesource.com/c/chromium/src/+/5906158
patch applied manually due to context shear
* chore: e patches all
* refactor!: Session.clearStorageData(syncable)
Xref: https://chromium-review.googlesource.com/c/chromium/src/+/6309405
Remove syncable type from opts.quota in Session.clearStorageData(opts)
because it that category has been removed upstream.
BREAKING CHANGE: Removed ses.clearDataStorage({ quota: 'syncable' })
* docs: deprecate Session.clearDataStorage({ quota })
---------
Co-authored-by: electron-roller[bot] <84116207+electron-roller[bot]@users.noreply.github.com>
Co-authored-by: Charles Kerr <charles@charleskerr.com>
* chore: bump chromium in DEPS to 136.0.7052.0
* chore: update mas_avoid_private_macos_api_usage.patch.patch
https://chromium-review.googlesource.com/c/chromium/src/+/6318359
patch applied manually due to context shear
* chore: update preconnect_manager.patch
Xref: https://chromium-review.googlesource.com/c/chromium/src/+/6318420
patch applied manually due to context shear
* chore: e patches all
* chore: bump chromium to 136.0.7053.1
* chore: update fix_remove_profiles_from_spellcheck_service.patch
Xref: https://chromium-review.googlesource.com/c/chromium/src/+/6326575
patch applied manually due to context shear
* chore: e patches all
* chore: revert removal of v8 API used by Node.js
* devtools: Remove DevToolsUIBindings::SendJsonRequest() | https://chromium-review.googlesource.com/c/chromium/src/+/6326236
* 6244461: Merge //content/common/user_agent.cc into //components/embedder_support:user_agent | https://chromium-review.googlesource.com/c/chromium/src/+/6244461
* 6313744: Migrate views::Background factory methods to ColorVariant | https://chromium-review.googlesource.com/c/chromium/src/+/6313744
* 6314545: Remove multiple argument support from base::ToString() | https://chromium-review.googlesource.com/c/chromium/src/+/6314545
* 6317362: [Extensions] Inline MessagingDelegate::CreateReceiverForTab() | https://chromium-review.googlesource.com/c/chromium/src/+/6317362
* 6308998: Add SettingAccess structured metrics event for DevTools | https://chromium-review.googlesource.com/c/chromium/src/+/6308998
* 6295214: Remove redundant state field in per-extension preferences | https://chromium-review.googlesource.com/c/chromium/src/+/6295214
NB: this change is copied from the upstream change to extensions/shell/browser/shell_extension_loader.cc
* fix: ui/ linter error
This is showing up in an eslint build step in Electron:
> /__w/electron/electron/src/out/Default/gen/ui/webui/resources/cr_elements/preprocessed/cr_menu_selector/cr_menu_selector.ts
> 77:23 error This assertion is unnecessary since the receiver accepts the original type of the expression @typescript-eslint/no-unnecessary-type-assertion
>
> ✖ 1 problem (1 error, 0 warnings)
> 1 error and 0 warnings potentially fixable with the `--fix` option.
However, removing the assertion causes a typescript build failure:
> gen/ui/webui/resources/cr_elements/preprocessed/cr_menu_selector/cr_menu_selector.ts:77:23 - error TS2345: Argument of type 'HTMLElement | null' is not assignable to parameter of type 'HTMLElement'.
> Type 'null' is not assignable to type 'HTMLElement'.
>
> 77 items.indexOf(this.querySelector<HTMLElement>(':focus'));
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
So I think the two different steps may be picking up typescript definitions.
This patch should be removed after the issue is tracked down
and fixed in a followup task.
* fix: -Wnonnull warning
Fixes this warning:
> 2025-03-07T01:05:01.8637705Z ../../third_party/electron_node/src/debug_utils.cc(257,12): error: null passed to a callee that requires a non-null argument [-Werror,-Wnonnull]
> 2025-03-07T01:05:01.8638267Z 257 | return nullptr;
> 2025-03-07T01:05:01.8638481Z | ^~~~~~~
> 2025-03-07T01:05:01.8638700Z 1 error generated.
Not sure why this warning was never triggered before; `git blame`
indicates this code hasn't changed in ages:
> c40a8273ef2 (Michaël Zasso 2024-05-10 09:50:20 +0200 255) #endif // DEBUG
> 8e2d33f1562 (Anna Henningsen 2018-06-07 16:54:29 +0200 256) }
> 247b5130595 (Refael Ackermann 2018-10-22 15:07:00 -0400 257) return nullptr;
> 247b5130595 (Refael Ackermann 2018-10-22 15:07:00 -0400 258) }
Presumably this is failing in this Chromium roll due to a
clang version bump.
We should remove this patch after upstreaming it.
* docs: add upstream pr link for Node patch
---------
Co-authored-by: electron-roller[bot] <84116207+electron-roller[bot]@users.noreply.github.com>
Co-authored-by: Charles Kerr <charles@charleskerr.com>
fix: javascript heap oom is not raised in node::OOMErrorHandler
node::OOMErrorHandler terminates the process directly without raising an
oom exception. To fix it, set an oom handler into node from electron.
fix: correct gin embedder indices.
Move electron extra embedders to the end of the enum so they do not
interfere with chromium embedders indices.
Also use kEmbedderBlinkTag directly in its index calculation without
adding extra indices from other tags.
> ### Removed:`isDefault` and `status` properties on `PrinterInfo`
> These properties have been removed from the PrinterInfo Object
> because they have been removed from upstream Chromium.
These properties won't be removed until Electron 36, but
breaking-changes.md lists them as being removed in 35.
This PR corrects the error.
* chore: bump chromium in DEPS to 135.0.7036.0
* chore: bump chromium in DEPS to 135.0.7037.0
---------
Co-authored-by: electron-roller[bot] <84116207+electron-roller[bot]@users.noreply.github.com>
* fix: re-enable synchronous spellcheck on Windows
* revert: fix: empty suggestions with windows platform checker
---------
Co-authored-by: Samuel Maddock <smaddock@slack-corp.com>
* feat: allow setting roundedCorners on Windows
* Update docs/api/structures/base-window-options.md
Co-authored-by: Will Anderson <will@itsananderson.com>
---------
Co-authored-by: Will Anderson <will@itsananderson.com>
This fixture has been calling process.exit() immediately after writing
to stdout and stderr, which the Node.js docs say is risky behavior:
> Calling process.exit() will force the process to exit as quickly as
> possible even if there are still asynchronous operations pending that
> have not yet completed fully, including I/O operations to
> process.stdout and process.stderr.
This fixture's been around for years without problems (AFAIK).
The writes are very small ('hello\n' and 'world') and finish quickly.
But recently I've been testing on a very slow CI machine. There, I see
this spec flaking when it expects stderr to be 'world' but it gets ''.
This PR changes the fixture to wait for stdout & stderr to flush
before calling process.exit().
* fix: close quick look during tests on macOS
* use longer delay 🤷
* fix: sharedPreviewPanel being recreated on close
* test: ensure preview panel gets closed
Added missing period for consistency and readability
Added a missing period in a specific part of the text to maintain consistency across the document. This ensures a uniform writing style, improves readability, and aligns with the formatting used throughout the content.
* test: disable unexpectedly quit dialog on macOS
* test: take screenshot before keyboard lock test
* Revert "test: take screenshot before keyboard lock test"
This reverts commit 3ba5c6984f.
* feat: Working navigationHistory.restore with just title/url
* feat: Restore page state, too
* chore: Docs, lint, tests
* Implement feedback
* More magic
* Make _awaitNextLoad truly private
* Implement API group feedback
* One more round of feedback
* fix: fix mksnapshot gen/v8 path
* build: use 7z compression
* build: unzip mksnapshot on Windows and update zip
* chore: escape backslashes
* chore: try another attempt
* chore: remove rmdir for now
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
Co-authored-by: David Sanders <dsanders11@ucsbalum.com>
When using `views::WebView` on macOS `NativeWidgetMacNSWindowHost`
contains a layer and compositor responsible for drawing web contents.
To trigger drawing `NativeWidgetMacNSWindowHost::OnVisibilityChanged`
needs to be called and `[NSWindow orderFrontRegardless]` does not trigger
`[NSWindow orderWindow:relativeTo:]` which can change
`NativeWidgetMacNSWindowHost` visiblity with stack:
```
views::NativeWidgetMacNSWindowHost::OnVisibilityChanged(bool)
remote_cocoa::NativeWidgetNSWindowBridge::OnVisibilityChanged()
-[ViewsNSWindowDelegate onWindowOrderChanged:]
-[NativeWidgetMacNSWindow orderWindow:relativeTo:]
```
`views::Widget` has method for showing inactive window:
`views::Widget::ShowInactive` which triggers
`NativeWidgetMacNSWindowHost::OnVisibilityChanged` with stack:
```
views::NativeWidgetMacNSWindowHost::OnVisibilityChanged(bool)
remote_cocoa::NativeWidgetNSWindowBridge::SetVisibilityState(remote_cocoa::mojom::WindowVisibilityState)
views::NativeWidgetMacNSWindowHost::SetVisibilityState(remote_cocoa::mojom::WindowVisibilityState)
views::NativeWidgetMac::Show(ui::mojom::WindowShowState, gfx::Rect const&)
views::Widget::ShowInactive() + 168
```
However this call seems to be insufficient to bring window to front,
therefore `[NSWindow orderFrontRegardless]` still needs to be called.
Calling `views::Widget::ShowInactive` ensures that all logic related to
showing Chromium widget will be properly executed, but onfortunately it
does not call `[NSWindow orderWindow:relativeTo:]` which is used to
disabling headless mode by the `ElectronNSWindow`, therefore we need to
trigger it manually through exposed `[ElectronNSWindow disableHeadlessMode]`.
Fixes: #45415
- Prefer GURL() when we want to return a non-reference empty URL.
- In ServiceWorkerMain::GetStorageKey(), use a reference instead
of instantiating a new temporary GURL.
From url/gurl.h:
> // Returns a reference to a singleton empty GURL. This object is for
> // callers who return references but don't have anything to return in
> // some cases. If you just want an empty URL for normal use, prefer
> // GURL().
* refactor: use MakeFixedFlatMap() in InclusionStatusToString()
* fix: add log message for EXCLUDE_ALIASING
refactor: add static_assert() to ensure our messages stay
in sync with the CookieInclusion reasons in net/cookies/
* feat: ServiceWorkerMain
* refactor: disconnect remote
* handle version_info_ nullptr case
* initiate finish request when possible and enumerate errors
* explicit name for test method
* oops
* fix: wait for redundant version to stop before destroying
* docs: clarify when undefined is returned
* chore: remove extra semicolons
* fix: backport patch to fix systemd unit activation in Chromium
This backports a patch from Chromium, which fixes systemd unit
activation. That is, a globalShortcuts feature that Chromium has
needs to create a systemd unit and rename it properly. Portal's
global shortcuts uses that name afterwards to map the app with
the shortcuts bound. However, there might be a race between
Chromium binding shortcuts and renaming the unit.
This is a first step to add Portal's globalShortcuts to
Electron.
* feat: Support global shortcuts via GlobalShortcutsPortal feature
Chromium has a new feature called GlobalShortcutsPortal. It
allows clients to use Portal's globalShortcuts to register and
listen to shortcuts.
This patches adds necessary bits, which allows Electron to
use that feature.
In order to make it work, one has to add
--enable-features=GlobalShortcutsPortal
Test: tested manually with a sample app.
* docs: add GlobalShortcutsPortal feature to globalShortcuts docs
Electron supports Portal's globalShortcuts API now via Chromium, and Electron
apps can use that in a Wayland session. Update the docs with the required
feature flag that must be passed to be able to use that implementation.
refactor: simplify StopTracing() a little by using a string_view instead of an optional<string>
We have compile-time string literals that we're passing to a method
that takes a string_view argument, so we don't need all this extra
optional<string> scaffolding
* refactor: remove InspectableWebContentsViewMac in favor of the Views version
* cherry-pick: refactor: remove InspectableWebContentsViewMac in favor of the Views version (#41326)
commit e67ab9a93d
Confilcts not resolved, except removal of the files removed
by the original commit.
* resolved conflicts and build issues after cherry-pick
* cherry-picked: fix: add method allowing to disable headless mode in native widget
https://github.com/electron/electron/pull/42996
fixing
https://github.com/electron/electron/issues/42995
* fix: displaying select popup in window created as fullscreen window
`constrainFrameRect:toScreen:` is not being call for windows created
with `fullscreen: true` therefore `headless` mode was not being removed
and `RenderWidgetHostNSViewBridge::DisplayPopupMenu` ignored displaying
popup.
Issue could be fixed by placing additional removal of `headless` mode
in the `toggleFullScreen:`, but `orderWindow:relativeTo:` is called
both for a regular and a fullscreen window, therefore there will be
a single place fixing both cases.
Because `electron::NativeWindowMac` lifetime may be shorter than
`ElectronNSWindow` on which macOS may execute `orderWindow:relativeTo:`
we need to clear `shell_` when `NativeWindow` is being closed.
Fixes#43010.
* fix: Content visibility when using `vibrancy`
We need to put `NSVisualEffectView` before `ViewsCompositorSuperview`
otherwise when using `vibrancy` in `BrowserWindow` `NSVisualEffectView`
will hide content displayed by the compositor.
Fixes#43003Fixes#42336
In fact main issues reported in these tickets were not present after
cherry-picking original refactor switching to `views::WebView`, so
text could be selected and click event was properly generated. However
both issues testcases were using `vibrancy` and actual content was
invisible, because it was covered by the `NSVisualEffectView`.
* fix: EXCEPTION_ACCESS_VIOLATION crash on BrowserWindow.destroy()
Restored postponed deletion of the `NativeWindow`.
Restoration caused `DCHECK(new_parent_ui_layer->GetCompositor());` failure
in `BrowserCompositorMac::SetParentUiLayer` after the spec test:
`chrome extensions chrome.webRequest does not take precedence over Electron webRequest - http`
with stack:
```
7 Electron Framework 0x000000011fe07830 content::BrowserCompositorMac::SetParentUiLayer(ui::Layer*) + 628
8 Electron Framework 0x000000011fe0c154 content::RenderWidgetHostViewMac::SetParentUiLayer(ui::Layer*) + 220
9 Electron Framework 0x000000011fe226a8 content::WebContentsViewMac::CreateViewForWidget(content::RenderWidgetHost*) + 600
10 Electron Framework 0x000000011fd37e4c content::WebContentsImpl::CreateRenderWidgetHostViewForRenderManager(content::RenderViewHost*) + 164
11 Electron Framework 0x000000011fb32278 content::RenderFrameHostManager::CreateSpeculativeRenderFrame(content::SiteInstanceImpl*, bool, scoped_refptr<content::BrowsingContextState> const&) + 816
12 Electron Framework 0x000000011fb2ab8c content::RenderFrameHostManager::CreateSpeculativeRenderFrameHost(content::SiteInstanceImpl*, content::SiteInstanceImpl*, bool) + 1308
13 Electron Framework 0x000000011fb28598 content::RenderFrameHostManager::GetFrameHostForNavigation(content::NavigationRequest*, content::BrowsingContextGroupSwap*, std::__Cr::basic_string<char, std::__Cr::char_traits<char>, std::__Cr::allocator<char>>*) + 1796
14 Electron Framework 0x000000011fa78660 content::NavigationRequest::SelectFrameHostForOnRequestFailedInternal(bool, bool, std::__Cr::optional<std::__Cr::basic_string<char, std::__Cr::char_traits<char>, std::__Cr::allocator<char>>> const&) + 280
15 Electron Framework 0x000000011fa6a994 content::NavigationRequest::OnRequestFailedInternal(network::URLLoaderCompletionStatus const&, bool, std::__Cr::optional<std::__Cr::basic_string<char, std::__Cr::char_traits<char>, std::__Cr::allocator<char>>> const&, bo
+ 1008
16 Electron Framework 0x000000011fa7772c content::NavigationRequest::OnRequestFailed(network::URLLoaderCompletionStatus const&) + 72
17 Electron Framework 0x000000011f8554ac content::NavigationURLLoaderImpl::NotifyRequestFailed(network::URLLoaderCompletionStatus const&) + 248
```
This was probably the reason of removing `NativeWindow` immediately
in order to cleanup `views_host_` in `WebContentsViewMac` to prevent
using layer without compositor in `WebContentsViewMac::CreateViewForWidget`.
`[ElectronNSWindowDelegate windowWillClose:]` is deleting window host
and the compositor used by the `NativeWindow` therefore detach `NativeWindow`
contents from parent. This will clear `views_host_` and prevent failing
mentioned `DCHECK`.
Fixes#42975
* chore: Applied review suggestions
* refactor: directly cleanup shell
---------
Co-authored-by: Samuel Maddock <smaddock@slack-corp.com>
In the old version of get-version.js, it replaces the leading 'v',
i.e. |output.stdout.toString().trim().replace(/^v/g, '')|. However,
in the new version of get-git-version.py, it directly replaces all
'v'. Obviously, it does not conform to the original semantics.
Although it will not affect the existing electron version calculation,
it may affect other developers' customized git-tag-version, such as
v0.0.0-dev.xxx, which will lose the 'v' of dev.
* fix: add patch to fix desktopCapturer.getSources not returning electron window on Windows
* add chromium link
* Update patches/chromium/fix_desktop_capturer_show_own_window.patch
Co-authored-by: Keeley Hammond <vertedinde@electronjs.org>
* fix on electron side
* set flag to true
* wrong capturer
---------
Co-authored-by: Keeley Hammond <vertedinde@electronjs.org>
Update window-setup.ts
The message should simply read "is not supported" or, alternatively, "is not, and will not, be supported", but not "is and will not be supported".
`ReadUnicodeCharacter` updates index to the last character read, and not after it. We need to manually increment it to move to the next character.
It also doesn't validate that the index is valid, so we need to check that index is within bounds.
Refs: #44336
* build: test windows runner
* build: try build windows on windows?
* build: take win/cross changes
* build: use bash as default shell always
* build: configure git for windows build tools
* build: bash as default
* build: configure windows correctly
* build: use sha1sum
* build: force windows cipd init and python3 existence
* just pain
* build: restore cache on windows
* build: use build-tools gclient
* build: sync gclient vars to build windows job
* build: output depshash for debugging
* build: past sam was a silly goose
* build: depshash logging
* build: force lf endings for lock and DEPS
* build: platform strings are hard
* build: checkout on windows host
* sup
* no check
* idk
* sigh
* ...
* no double checkout
* build: yolo some stuff
* build: run gn-check for windows on linux hosts for speed
* use container...
* cry ?
* build: e d
* e d
* no log
* fix toolchain on windows cross check
* build: use powershell to add mksnapshot_args
* build: enable x86 and arm64 windows builds too
* clean up
* maybe not needed
* build: keep action around for post step
* build: configure git global on win
* build: ia32 zip manifest
* build: no patch depot_tools for tests
* build: get arm64 windows closer to working
* build: windows tar is ass
* 32 bit on 32 bit
* maybe bash
* build: set up nodejs
* correct windows sharding
* fix some spec runner stuff
* fix windows tests
* overwrite -Force
* sigh
* screen res
* wat
* logs
* ... more logs
* line endings will be the death of me
* remove 1080p force thing
* vsctools + logging
* disable some fullscreen tests on GHA
* no progress
* run all CI
* install visual studio on arm64
* windows hax for non windows
* maybe arm sdk
* clean up depshash logic
* build: use single check per platform
* ensure clean args
* fix loop
* remove debug
* update default build image sha for dispatch
* plzzzz
* one more try
* arm64 vctools
* sad
* build: fix non-dispatch windows gn check
* chore: debug datadog-ci location
* chore: update build-tools for newer toolchain
* chore: set path for datadog-ci
* try this
* chore: fixup gn check
* fixup gn-check some more
* fixup windows gn check
* chore: fixup windows gn check
* test: use cmd for Windows testing
* fixup use cmd for testing on Windows
* fixup windows GN check
* fixup npm config arch for x86
* Can we set test files via powershell
* fixup to set test files via powershell
* fixup set test files via powershell
* Don't check cross instance cache disk space on Windows
* Use separate step to set env variables for testing
* fixup Use separate step to set env variables for testing
* fixup Use separate step to set env variables for testing
* fixup Use separate step to set env variables for testing (AGAIN)
* use powershell if in powershell
* fixup use powershell if in powershell
* chore: remove no longer needed changes to depot_tools
xref: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/5669094
and https://chromium-review.googlesource.com/c/chromium/src/+/5844046
* chore: try using 7zip on Windows to extract tarball
* Revert "chore: try using 7zip on Windows to extract tarball"
This reverts commit c7432b6a37.
* test: debug failing tests on GHA windows
* fix: ftbfs when including simdjson in Node.js
(cherry picked from commit 48e44c40d6)
* chore: try to track down Windows testing hang
* use correct timeout
* try this
* see if this helps
* try to figure out why node is running
* shard tests to try to narrow down WOA lockup
* try to narrow down problem test
* Narrow down blocking test more
* do we need a combo to repro
* see if this cleans up the tests
* fixup navigator.usb test
* remove logging from problematic tests
* Revert "shard tests to try to narrow down WOA lockup"
This reverts commit a180658376.
* remove logging
* debug keyboard test
* add timeout for Windows since arm64 sometimes hangs
* see if this helps
* put back original timeout
* try to use screenCapture to get screenshots of what is going on on WOA
* try using electron screencapture to debug WOA hang
* chore: turn off privacy experience
* run screenshot on both shards
* fixup screencap
* try to narrow down hanging spec
* chore: cleanup servers left open
* cleanup tests
* Revert "try to narrow down hanging spec"
This reverts commit a0f959f538.
* cleanup test debugging
* fixup extensions spec
* cleanup unneeded items
* run wtf with 2 shards instead of 6
* Revert "run wtf with 2 shards instead of 6"
This reverts commit ca2d282129.
* debug windows version on woa
* dump more info
* Get detailed CPU info
* revert debugging
* use same args as AppVeyor WOA for GHA WOA
* fixup use same args as AppVeyor WOA for GHA WOA
* fixup use same args as AppVeyor WOA for GHA WOA
* try to track down which tests trigger hang
* one or more of these combinations should hang
* break up web contents spec to find hang
* further break down api-web-contents to find hang
* test: ensure all webContents are closed
* test: fix require is not defined error
* see if api-web-contents spec is now good
* test: ensure all webContents are closed
* Revert "try to track down which tests trigger hang"
This reverts commit 07298d6ffe.
* chore: use alternate location for windows toolchain
* Reapply "try to track down which tests trigger hang"
This reverts commit 0321f76d01.
* try to narrow down problem test
* fix TEST_SHARD env var
* no, really fix TEST_SHARD env var
* see if this fixes it
* test: cleanup any remaining windows and webcontents
* see if new cleanup helps
* dont destroy webcontents for now
* fixup dont destroy webcontents for now
* Only cleanup right before process.exit
* see if this fixes the hang
* actually destroy webcontents
* Revert "Reapply "try to track down which tests trigger hang""
This reverts commit cdee7de049.
* see if this helps
* Revert "see if this helps"
This reverts commit 9a15a69cf7.
* Is it all about the web contents?
* it is all about the webcontents
but which one?
* Narrow down problem webcontents test
* try to speed up git install on WOA
* disable problematic test on WOA
* remove debugging
* remove debugging from choco installs
* Revert "disable problematic test on WOA"
This reverts commit e060fb0839.
* Revert "remove debugging"
This reverts commit f18dd8b1a5.
* run against all the tests in the failing shard
* don't run visibility tests first
* remove debugging
* 3 is a magic number
* Revert "3 is a magic number"
This reverts commit 36b91ccf9f.
* match what Appveyor runs exactly
* Revert "match what Appveyor runs exactly"
This reverts commit 7260dd4322.
* chore: sort files alphabetically
* find out what spec is leaving stuff open
* chore: Checkout PR HEAD commit
instead of merge commit
* try using app.exit instead of process.exit
* test: cleanup BrowserWindows and webContents
* Revert "chore: sort files alphabetically"
This reverts commit d9e217ffb1.
* chore: use win32 to match process.platform
Needed for build-tools to download from PRs
* chore: cache yarn dir
* fixup cache yarn
* fixup use win32 to match process.platform
* fixup use win32 to match process.platform
* fixup cache yarn
* Add debugging for WOA hang
* Add debugging for failing keyboard lock test
* Revert "Add debugging for WOA hang"
This reverts commit 8df03d568d.
* try using process.kill
* add more debugging to keyboard.lock test
* Revert "Add debugging for failing keyboard lock test"
* remove debugging
* test: disable keyboard.lock on Windows
* test: disable fullscreen tests on Windows
* test: only force test suite exit on WOA
* fixup test: only force test suite exit on WOA
* cleanup tests
* extract yarn caching/install to action
* try using bash to run windows tests
* remove left over debugging
* standardize on 'win' for Windows builds
* use 'x86' for arch for manifest files
* fixup try using bash to run windows tests
* fixup use 'x86' for arch for manifest files
* standardize on 'win' for Windows builds
* fixup use 'x86' for arch for manifest files
* fixup try using bash to run windows tests
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
Co-authored-by: Charles Kerr <charles@charleskerr.com>
* fix: unused variable warning when the PDF viewer is disabled
* fix: unused function error when PDF viewer is disabled
error: unused function ParseManifest [-Werror,-Wunused-function]
* docs: clarify what session.clearData() with data type 'cache' deletes
* docs: include `shadercache`, too
Co-authored-by: John Kleinschmidt <kleinschmidtorama@gmail.com>
---------
Co-authored-by: John Kleinschmidt <kleinschmidtorama@gmail.com>
* chore: remove unused isolate argument from Cookies constructor
unused since the ginify cookies refactor in Mar 2020, commit 22202255
* fix: constructor only takes one arg now, so mark it explicit
* refactor: make kRelauncherArgSeparator private to relauncher.cc
* refactor: make kRelauncherTypeArg private to relauncher.cc
* refactor: remove unused type relauncher::CharType
* refactor: move private constants into standalone private namespace
* refactor: move kWaitEventName into the only function that uses it
* refactor: more return-braced-init-list, this time for v8 and gin objects
* refactor: more return-braced-init-list, this time for v8, gin, std, and base objects
* refactor: misc-use-internal-linkage warnings in context bridge
move impl functions into anonymous namespace so that they're not visible
to other compilation units:
- ExposeAPIInWorld()
- IsCalledFromMainWorld()
- OverrideGlobalPropertyFromIsolatedWorld()
- OverrideGlobalValueFromIsolatedWorld()
- TraceKeyPath()
* refactor: misc-use-internal-linkage warnings in skia util
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- struct ScaleFactorPair
- kScaleFactorPairs[]
- GetScaleFactorFromPath()
- AddImageSkiaRepFromPath()
* refactor: misc-use-internal-linkage warnings in printing util
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- GetFullPagePlugin()
* refactor: misc-use-internal-linkage warnings in blijnk converter
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- GetKeyLocationCode()
- ModifiersToArray()
* refactor: misc-use-internal-linkage warnings in extrension system
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- ParseManifest()
* refactor: misc-use-internal-linkage warnings in skia util
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- GetFrameTokenMap()
- GetFrameTreeNodeIdMap()
* refactor: misc-use-internal-linkage warnings in electron_api_utility_process.cc
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- GetAllUtilityProcessWrappers()
* refactor: misc-use-internal-linkage warnings in electron_api_menu
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- InvokeBoolMethod()
* refactor: misc-use-internal-linkage warnings in platform util
move impl details into anonymous namespace so that they're not visible
to other compilation units:
- struct TrashItemResult
- TrashItemOnBlockingThread()
* refactor: avoid repeating the return type from the declaration; use a braced initializer list instead [modernize-return-braced-init-list]
* refactor: avoid repeating the return type from the declaration; use a braced initializer list instead [modernize-return-braced-init-list]
NB: using the braced-initializer list uncovered an error here:
the float returned by std::floor() can't be implicitly cast to
an int. This is solved by using base::ClampFloor<int>() instead.
std::floor()
* chore: remove unused local non-trivial variable relaunch_executable
became unused in June 2016 in 0d066de5
* chore: only declare program_name local variable if used
We declared it everywhere but only used it on Windows
* chore: remove unused local non-trivial variable path from UnregisterXWindow
it became unused in 2020 by 72a08926
* feat: add query-session-end event for Windows
* fix: remove debug line
* feat: notify with reason on session-end
* docs: add comments and return params
* docs: add same docs to the BrowserWindow
* fix: add shutdown reason if lParam == 0
* docs: remove 'force' word
* docs: revert multithreading.md change
* docs: add reasons documentation, reason variable renamed to reasons
* docs: improve 'shutdown' reason wording
* docs: reword with 'can be'
* fix: pass reasons by reference
* fix: use newer approach which expose reasons value directly on Event object
* docs: add escaping
* style: linter fixes
* fix: project now should compile
* fix: EmitWithoutEvent method added, EmitWithEvent moved to private again
* docs: typo fix
Co-authored-by: Sam Maddock <samuel.maddock@gmail.com>
* docs: dedicated WindowSessionEndEvent type created
* docs: better wording for session-end event description
Co-authored-by: Will Anderson <will@itsananderson.com>
---------
Co-authored-by: Sam Maddock <samuel.maddock@gmail.com>
Co-authored-by: Will Anderson <will@itsananderson.com>
* fix: performance-no-automatic-move in GetLogFileName()
remove `const` from log_filename.
Warning fixed by this commit:
../../electron/shell/common/logging.cc:40:12: warning: constness of 'log_filename' prevents automatic move [performance-no-automatic-move]
* fix: performance-no-automatic-move in GetBundleResourcePath()
remove `const` from request_relative_path.
Warning fixed by this commit:
electron/shell/browser/extensions/electron_extensions_browser_client.cc:187:10: warning: constness of 'request_relative_path' prevents automatic move [performance-no-automatic-move]
* refactor: use gdk_display_beep() to beep on Linux
* chore: make a stub declaration for gdk_display_beep()
* chore: remove unused file electron_gtk.sigs
* chore: remove unused #includes to make gn check happy
* fix: bugprone-narrowing-conversions warning in NativeImage::memory_usage_
- fix signed / unsigned math by using base/numerics/safe_conversions
- make memory_usage_ an int64_t so it can safely take the size_t
returned by computeByteSize()
Warning fixed by this commit:
../../electron/shell/common/api/electron_api_native_image.cc:155:26: warning: narrowing conversion from 'size_t' (aka 'unsigned long') to signed type 'int32_t' (aka 'int') is implementation-defined [bugprone-narrowing-conversions]
155 | new_memory_usage = image_skia->bitmap()->computeByteSize();
* fix: bugprone-narrowing-conversions warnings in NativeImage::CreateFromBitmap()
`SkImageInfo::MakeN32()` and `SkBitmap::allocN32Pixels()` both take int
width and height args, but we were feeding them unsigned ints.
../../electron/shell/common/api/electron_api_native_image.cc:508:36: warning: narrowing conversion from 'unsigned int' to signed type 'int' is implementation-defined [bugprone-narrowing-conversions]
508 | auto info = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType);
| ^
../../electron/shell/common/api/electron_api_native_image.cc:508:43: warning: narrowing conversion from 'unsigned int' to signed type 'int' is implementation-defined [bugprone-narrowing-conversions]
508 | auto info = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType);
| ^
../../electron/shell/common/api/electron_api_native_image.cc:524:25: warning: narrowing conversion from 'unsigned int' to signed type 'int' is implementation-defined [bugprone-narrowing-conversions]
524 | bitmap.allocN32Pixels(width, height, false);
| ^
../../electron/shell/common/api/electron_api_native_image.cc:524:32: warning: narrowing conversion from 'unsigned int' to signed type 'int' is implementation-defined [bugprone-narrowing-conversions]
524 | bitmap.allocN32Pixels(width, height, false);
| ^
../../electron/shell/common/api/electron_api_native_image.cc:528:48: warning: narrowing conversion from 'double' to 'float' [bugprone-narrowing-conversions]
528 | gfx::ImageSkia::CreateFromBitmap(bitmap, scale_factor);
fix: AutofillPopup warning: use '= default' to define a trivial default constructor [modernize-use-equals-default]
refactor: reduce #indclude scope in autofill_popup.h and autofill_popup_view.h
* chore: reland "fix: utility process exit code for graceful termination"
This reverts commit 1cae73ba09.
* fix: exit code on posix when killed via api
* chore: fix code style
* docs: Make ipcRenderer and ipcMain listener API docs consistent
* test: add some unit tests for ipcRenderer/ipcMain listener behavior
* fix: Mark on/off methods as primary and addListener/removeListener as aliases
* fix: clear all listeners before running ipcMain removeAllListeners tests
* feat: add support for configuring xdg portal version at runtime
* doc: update command-line-switches.md
* doc: update command-line-switches.md
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
* doc: required portal version for defaultPath support
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
* doc: update more occurrances
* fix: remove warning from save dialogs
* doc: update command-line-switches.md
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
Closes https://github.com/electron/electron/issues/44569.
Fixes an issue where the WCO buttons were hidden on Linux in fullscreen mode
but not on Windows or macOS. The Windows behavior is the expected one, so this
commit makes the Linux behavior consistent.
Update Squirrel Run at Login docs to be modern
The current docs for setting up Run at Login use the legacy way that
Squirrel does shortcuts. This was replaced by an easier method, let's
use that instead
* fix: flake wait for crash with specific serviceName
* fix: flake when unrelated WebContents exists during BrowserView tests
* fix: wait for crash before forking
* use name
* fix: Use openURL:configuration:completionHandler instead of openUrl
* test: add a test
* fix: add dispatch_async to replace GetUIThreadTaskRunner
* refactor: remove unused import
* fix: update to use BindPostTaskToCurrentDefault
* test: add regression test for window focus
* refactor: update to explicit task runner
* refactor: move uv_setup_args() calls to startup
* refactor: call base::CommandLine::Init() before ContentMain()
* feat: add ElectronCommandLine::AsUtf8()
* refactor: call base::CommandLine::Init() before NodeMain()
* refactor: use ElectronCommandLine::AsUtf8() in NodeMain()
* fix: -Wunsafe-buffer-usage warning in ElectronCommandLine::Init()
* chore: add a DCHECK to confirm ElectronCommandLine was initialized before AsUtf8() is called
* chore: const correctness in ElectronCommandLine::Init() args
* chore: add ElectronCommandLine to macOS Electron Helper app
* chore: move argc, argvc setup into electron_library_main on macOS
* chore: revert BUILD.gn changes
* fix: WideToUTF8() call in ElectronCommandLine::AsUtf8()
* build: add uv to the include paths for app/electron_main_linux
* build: add uv to the include paths for app/electron_library_main.mm
* chore: revert unrelated changes
these were intended for another branch
* refactor: BaseWindow::OnExecuteAppCommand() now takes a std::string_view
* refactor: NativeWindow::NotifyWindowExecuteAppCommand() takes a std::string_view
* refactor: AppCommandToString() returns a std::string_view, is now constexpr
* refactor: make kBrowserBackward, kBrowserForward inline constexpr std::string_view
Xref: https://abseil.io/tips/140https://groups.google.com/a/chromium.org/g/chromium-dev/c/jROTxMo_m2Q/m/HgciN2KsAgAJ
* refactor: use inline constexpr string_view for kDevice*Key constants
Xref: https://abseil.io/tips/140https://groups.google.com/a/chromium.org/g/chromium-dev/c/jROTxMo_m2Q/m/HgciN2KsAgAJ
* refactor: IsEnvSet now takes a base::cstring_view
* refactor: use inline constexpr cstring_view for kRunAsNode
* refactor: use inline constexpr string_view for kPDF*PluginName
* refactor: use base::FilePath::FromASCII() since "internal-pdf-viewer" is ascii
* chore: remove unused shell/common/electron_constants.cc
* fixup! refactor: IsEnvSet now takes a base::cstring_view
* perf: prefer NewFromUtf8Literal() over NewFromUtf8() for string literals
the string length is known at compile time and no need to call ToLocalChecked()
* perf: string length is known when calling NewFromUtf8(), so use it
* perf: remove unnecessary calls to c_str()
these just force the code being called to have to recalculate the string length
* chore: move as_byte_span() to new shell/common/mac_util.h
this way it can be used by multiple mm files
* fix: -Wunsafe-buffer-usage warnings in UNNotificationResponseToNSDictionary
* refactor: use base::HexEncode() instead of rolling our own
* fixup! chore: move as_byte_span() to new shell/common/mac_util.h
* fixup! chore: move as_byte_span() to new shell/common/mac_util.h
fix: move mac_util to the right place in filenames.gni
description:Only to be created by Electron maintainers
body:
- type:checkboxes
attributes:
label:Confirmation
options:
- label:I am a [maintainer](https://github.com/orgs/electron/people) of the Electron project. (If not, please create a [different issue type](https://github.com/electron/electron/issues/new/).)
- [ ] PR description included and stakeholders cc'd
- [ ]`npm test` passes
- [ ] tests are [changed or added](https://github.com/electron/electron/blob/main/docs/development/testing.md)
- [ ] relevant documentation, tutorials, templates and examples are changed or added
- [ ] relevant API documentation, tutorials, and examples are updated and follow the [documentation style guide](https://github.com/electron/electron/blob/main/docs/development/style-guide.md)
- [ ] [PR release notes](https://github.com/electron/clerk/blob/main/README.md) describe the change in a way relevant to app developers, and are [capitalized, punctuated, and past tense](https://github.com/electron/clerk/blob/main/README.md#examples).
Emitted when a session is about to end due to a shutdown, machine restart, or user log-off. Once this event fires, there is no way to prevent the session from ending.
#### Event: 'blur'
@@ -512,7 +526,7 @@ Sets the content view of the window.
#### `win.getContentView()`
Returns [View](view.md) - The content view of the window.
Returns [`View`](view.md) - The content view of the window.
#### `win.destroy()`
@@ -1429,3 +1443,4 @@ On Linux, the `symbolColor` is automatically calculated to have minimum accessib
Emitted when a session is about to end due to a shutdown, machine restart, or user log-off. Once this event fires, there is no way to prevent the session from ending.
#### Event: 'unresponsive'
@@ -1549,13 +1563,17 @@ there is only one tab in the current window.
Adds a window as a tab on this window, after the tab for the window instance.
#### `win.setVibrancy(type)` _macOS_
#### `win.setVibrancy(type[, options])` _macOS_
* `type` string | null - Can be `titlebar`, `selection`, `menu`, `popover`, `sidebar`, `header`, `sheet`, `window`, `hud`, `fullscreen-ui`, `tooltip`, `content`, `under-window`, or `under-page`. See
the [macOS documentation][vibrancy-docs] for more details.
* `options` Object (optional)
* `animationDuration` number (optional) - if greater than zero, the change to vibrancy will be animated over the given duration (in milliseconds).
Adds a vibrancy effect to the browser window. Passing `null` or an empty string
will remove the vibrancy effect on the window.
will remove the vibrancy effect on the window. The `animationDuration` parameter only
animates fading in or fading out the vibrancy effect. Animating between
@@ -360,7 +360,7 @@ On Windows the options are more limited, due to the Win32 APIs used:
## Bookmarks array
`showOpenDialog`, `showOpenDialogSync`, `showSaveDialog`, and `showSaveDialogSync` will return a `bookmarks` array.
`showOpenDialog` and `showSaveDialog` resolve to an object with a `bookmarks` field. This field is an array of Base64 encoded strings that contain the [security scoped bookmark](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) data for the saved file. The `securityScopedBookmarks` option must be enabled for this to be present.
| Build Type | securityScopedBookmarks boolean | Return Type | Return Value |
Emitted when a service worker has been registered. Can occur after a call to [`navigator.serviceWorker.register('/sw.js')`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register) successfully resolves or when a Chrome extension is loaded.
*`versionId` number - ID of the updated service worker version
*`runningStatus` string - Running status.
Possible values include `starting`, `running`, `stopping`, or `stopped`.
Emitted when a service worker's running status has changed.
### Instance Methods
The following methods are available on instances of `ServiceWorkers`:
@@ -64,10 +75,55 @@ The following methods are available on instances of `ServiceWorkers`:
Returns `Record<number, ServiceWorkerInfo>` - A [ServiceWorkerInfo](structures/service-worker-info.md) object where the keys are the service worker version ID and the values are the information about that service worker.
*`versionId` number - ID of the service worker version
Returns [`ServiceWorkerMain | undefined`](service-worker-main.md) - Instance of the service worker associated with the given version ID. If there's no associated version, or its running status has changed to 'stopped', this will return `undefined`.
*`colorDepth` number - The number of bits per pixel.
*`colorSpace` string - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversions.
*`depthPerComponent` number - The number of bits per color component.
*`detected` boolean - `true`` if the display is detected by the system.
*`detected` boolean - `true` if the display is detected by the system.
*`displayFrequency` number - The display refresh rate.
*`id` number - Unique identifier associated with the display. A value of of -1 means the display is invalid or the correct `id` is not yet known, and a value of -10 means the display is a virtual display assigned to a unified desktop.
*`internal` boolean - `true` for an internal display and `false` for an external display.
*`type` String - Possible values include `service-worker`.
*`serviceWorker` [ServiceWorkerMain](../service-worker-main.md) _Readonly_ - The service worker that sent this message
*`versionId` Number - The service worker version ID.
*`session` Session - The [`Session`](../session.md) instance with which the event is associated.
*`returnValue` any - Set this to the value to be returned in a synchronous message
*`ports` [MessagePortMain](../message-port-main.md)[] - A list of MessagePorts that were transferred with this message
*`reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guarantee the reply will go to the correct process and frame.
*`name` string - the name of the printer as understood by the OS.
*`displayName` string - the name of the printer as shown in Print Preview.
*`description` string - a longer description of the printer's type.
*`status` number - the current status of the printer.
*`isDefault` boolean - whether or not a given printer is set as the default printer on the OS.
*`options` Object - an object containing a variable number of platform-specific printer information.
The number represented by `status` means different things on different platforms: on Windows its potential values can be found [here](https://learn.microsoft.com/en-us/windows/win32/printdocs/printer-info-2), and on Linux and macOS they can be found [here](https://www.cups.org/doc/cupspm.html).
@@ -19,8 +17,6 @@ may be different on each platform.
*`scriptUrl` string - The full URL to the script that this service worker runs
*`scope` string - The base URL that this service worker is active for.
*`renderProcessId` number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for `webContents.getProcessId()`.
*`versionId` number - ID of the service worker version
*`urls` string[] - Array of [URL patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) that will be used to filter out the requests that do not match the URL patterns.
*`types`String[] (optional) - Array of types that will be used to filter out the requests that do not match the types. When not specified, all types will be matched. Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media` or `webSocket`.
*`urls` string[] - Array of [URL patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) used to include requests that match these patterns. Use the pattern `<all_urls>` to match all URLs.
*`excludeUrls`string[] (optional) - Array of [URL patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) used to exclude requests that match these patterns.
*`types` string[] (optional) - Array of types that will be used to filter out the requests that do not match the types. When not specified, all types will be matched. Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media` or `webSocket`.
@@ -898,6 +898,8 @@ copying data between CPU and GPU memory, with Chromium's hardware acceleration s
Only a limited number of textures can exist at the same time, so it's important that you call `texture.release()` as soon as you're done with the texture.
By managing the texture lifecycle by yourself, you can safely pass the `texture.textureInfo` to other processes through IPC.
More details can be found in the [offscreen rendering tutorial](../tutorial/offscreen-rendering.md). To learn about how to handle the texture in native code, refer to [offscreen rendering's code documentation.](https://github.com/electron/electron/blob/main/shell/browser/osr/README.md).
@@ -12,8 +12,99 @@ This document uses the following convention to categorize breaking changes:
* **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 (36.0)
### Utility Process unhandled rejection behavior change
Utility Processes will now warn with an error message when an unhandled
rejection occurs instead of crashing the process.
To restore the previous behavior, you can use:
```js
process.on('uncaughtException',()=>{
process.exit(1)
})
```
### Removed:`isDefault` and `status` properties on `PrinterInfo`
These properties have been removed from the PrinterInfo Object
because they have been removed from upstream Chromium.
### Removed: `quota` type `syncable` in `Session.clearStorageData(options)`
When calling `Session.clearStorageData(options)`, the `options.quota` type
`syncable` is no longer supported because it has been
Additionally, `level` is now a string with possible values of `info`, `warning`, `error`, and `debug`.
### Behavior Changed: `urls` property of `WebRequestFilter`.
Previously, an empty urls array was interpreted as including all URLs. To explicitly include all URLs, developers should now use the `<all_urls>` pattern, which is a [designated URL pattern](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns#all_urls) that matches every possible URL. This change clarifies the intent and ensures more predictable behavior.
One of Electron's most powerful features is the ability to combine web technologies with native code - both for compute-intensive logic as well as for the occasional native user interface, where desired.
Electron does so by building on top of "Native Node.js Addons". You've probably already come across a few of them - packages like the famous [sqlite](https://www.npmjs.com/package/sqlite3) use native code to combine JavaScript and native technologies. You can use this feature to extend your Electron application with anything a fully native application can do:
* Access native platform APIs not available in JavaScript. Any macOS, Windows, or Linux operating system API is available to you.
* Create UI components that interact with native desktop frameworks.
* Integrate with existing native libraries.
* Implement performance-critical code that runs faster than JavaScript.
Native Node.js addons are dynamically-linked shared objects (on Unix-like systems) or DLL files (on Windows) that can be loaded into Node.js or Electron using the `require()` or `import` functions. They behave just like regular JavaScript modules but provide an interface to code written in C++, Rust, or other languages that can compile to native code.
# Tutorial: Creating a Native Node.js Addon for Electron
This tutorial will walk you through building a basic Node.js native addon that can be used in Electron applications. We'll focus on concepts common to all platforms, using C++ as the implementation language. Once you complete this tutorial common to all native Node.js addons, you can move on to one of our platform-specific tutorials.
## Requirements
This tutorial assumes you have Node.js and npm installed, as well as the basic tools necessary for compiling code on your platform (like Visual Studio on Windows, Xcode on macOS, or GCC/Clang on Linux). You can find detailed instructions in the [`node-gyp` readme](https://github.com/nodejs/node-gyp?tab=readme-ov-file).
### Requirements: macOS
To build native Node.js addons on macOS, you'll need the Xcode Command Line Tools. These provide the necessary compilers and build tools (namely, `clang`, `clang++`, and `make`). The following command will prompt you to install the Command Line Tools if they aren't already installed.
```sh
xcode-select --install
```
### Requirements: Windows
The official Node.js installer offers the optional installation of "Tools for Native Modules", which installs everything required for the basic compilation of C++ modules - specifically, Python 3 and the "Visual Studio Desktop development with C++" workload. Alternatively, you can use `chocolatey`, `winget`, or the Windows Store.
### Requirements: Linux
* [A supported version of Python](https://devguide.python.org/versions/)
*`make`
* A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org)
## 1) Creating a package
First, create a new Node.js package that will contain your native addon:
```sh
mkdir my-native-addon
cd my-native-addon
npm init -y
```
This creates a basic `package.json` file. Next, we'll install the necessary dependencies:
```sh
npm install node-addon-api bindings
```
*`node-addon-api`: This is a C++ wrapper for the low-level Node.js API that makes it easier to build addons. It provides a C++ object-oriented API that's more convenient and safer to use than the raw C-style API.
*`bindings`: A helper module that simplifies the process of loading your compiled native addon. It handles finding your compiled `.node` file automatically.
Now, let's update our `package.json` to include the appropriate build scripts. We will explain what these specifically do further below.
* `clean`: Remove the build directory, allowing for a fresh build
* `build`: Run the standard node-gyp build process to compile your addon
## 2) Setting up the build system
Node.js addons use a build system called `node-gyp`, which is a cross-platform command-line tool written in Node.js. It compiles native addon modules for Node.js using platform-specific build tools behind the scenes:
* On Windows: Visual Studio
* On macOS: Xcode or command-line tools
* On Linux: GCC or similar compilers
### Configuring `node-gyp`
The `binding.gyp` file is a JSON-like configuration file that tells node-gyp how to build your native addon. It's similar to a make file or a project file but in a platform-independent format. Let's create a basic `binding.gyp` file:
* `target_name`: The name of your addon. This determines the filename of the compiled module (my_addon.node).
* `sources`: List of source files to compile. We'll have two files: the main addon file and our actual C++ implementation.
* `include_dirs`: Directories to search for header files. The cryptic-looking line `<!@(node -p \"require('node-addon-api').include\")` runs a Node.js command to get the path to the node-addon-api include directory.
* `dependencies`: The `node-addon-api` dependency. Similar to the include dirs, this executes a Node.js command to get the proper configuration.
* `defines`: Preprocessor definitions. Here we're enabling C++ exceptions for node-addon-api.
Platform-specific settings:
* `cflags`! and cflags_cc!: Compiler flags for Unix-like systems
* `xcode_settings`: Settings specific to macOS/Xcode compiler
* `msvs_settings`: Settings specific to Microsoft Visual Studio on Windows
Now, create the directory structure for our project:
```sh
mkdir src
mkdir include
mkdir js
```
This creates:
* `src/`: Where our source files will go
* `include/`: For header files
* `js/`: For our JavaScript wrapper
## 3) "Hello World" from C++
Let's start by defining our C++ interface in a header file. Create `include/cpp_code.h`:
```cpp
#pragma once
#include <string>
namespace cpp_code {
// A simple function that takes a string input and returns a string
The `#pragma once` directive is a header guard that prevents the file from being included multiple times in the same compilation unit. The actual function declaration is inside a namespace to avoid potential name conflicts.
Next, let's implement the function in `src/cpp_code.cc`:
console.warn('Native addon not supported on this platform')
module.exports = {
helloWorld: (input) => `Hello from JS! You said: ${input}`
}
}
```
This JavaScript wrapper:
1. Uses `bindings` to load our compiled native addon
1. Creates a class that extends EventEmitter (useful for future extensions that might emit events)
1. Instantiates our C++ class and provides a simpler API
1. Adds some input validation on the JavaScript side
1. Exports a singleton instance of our wrapper
1. Handles unsupported platforms gracefully
### Building and testing the addon
Now we can build our native addon:
```sh
npm run build
```
This will run `node-gyp configure` and `node-gyp build` to compile our C++ code into a `.node` file.
Let's create a simple test script to verify everything works. Create `test.js` in the project root:
```js title='test.js' @ts-expect-error=[2]
// Load our addon
const myAddon = require('./js')
// Try the helloWorld function
const result = myAddon.helloWorld('This is a test')
// Should print: "Hello from C++! You said: This is a test"
console.log(result)
```
Run the test:
```sh
node test.js
```
If everything works correctly, you should see:
```txt
Hello from C++! You said: This is a test
```
### Using the addon in Electron
To use this addon in an Electron application, you would:
1. Include it as a dependency in your Electron project
1. Build it targeting your specific Electron version. `electron-forge` handles this step automatically for you - for more details, see [Native Node Modules](./using-native-node-modules.md).
1. Import and use it just like any other module in a process that has Node.js enabled.
```js @ts-expect-error=[2]
// In your main process
const myAddon = require('my-native-addon')
console.log(myAddon.helloWorld('Electron'))
```
## References and further learning
Native addon development can be written in several languages beyond C++. Rust can be used with crates like [`napi-rs`](https://github.com/napi-rs/napi-rs), [`neon`](https://neon-rs.dev/), or [`node-bindgen`](https://github.com/infinyon/node-bindgen). Objective-C/Swift can be used through Objective-C++ on macOS.
The specific implementation details differ significantly by platform, especially when accessing platform-specific APIs or UI frameworks, like Windows' Win32 API, COM components, UWP/WinRT - or macOS's Cocoa, AppKit, or ObjectiveC runtime.
This means that you'll likely use two groups of references for your native code: First, on the Node.js side, use the [N-API documentation](https://nodejs.org/api/n-api.html) to learn about creating and exposing complex structures to JavaScript - like asynchronous thread-safe function calls or creating JavaScript-native objects (`error`, `promise`, etc). Secondly, on the side of the technology you're working with, you'll likely be looking at their lower-level documentation:
* [Microsoft C++, C, and Assembler documentation](https://learn.microsoft.com/en-us/cpp/?view=msvc-170)
* [Programming with Objective-C](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011210)
@@ -22,7 +22,7 @@ If you want to focus on building a great product without figuring out how you ca
### Reliability
Web technologies are the most-used foundation for user interfaces on the planet. The have been hardened accordingly. Modern computers have been optimized from the CPU to the operating system to be good at running web technologies. The manufacturers of your user’s devices—be that an Android phone or the latest MacBook—will ensure that they can visit websites, play videos on YouTube, or display emails. In turn, they’ll also ensure that your app has a stable foundation, even if you have just one user.
Web technologies are the most-used foundation for user interfaces on the planet. They have been hardened accordingly. Modern computers have been optimized from the CPU to the operating system to be good at running web technologies. The manufacturers of your user’s devices—be that an Android phone or the latest MacBook—will ensure that they can visit websites, play videos on YouTube, or display emails. In turn, they’ll also ensure that your app has a stable foundation, even if you have just one user.
If you want to focus on building a great product without debugging a weird quirk that nobody has found before, the web is a safe bet.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
