New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: explain avoiding top-level await with whenReady #41369
base: main
Are you sure you want to change the base?
Conversation
💖 Thanks for opening this pull request! 💖 We use semantic commit messages to streamline the release process. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix. Examples of commit messages with semantic prefixes:
Things that will help get your PR across the finish line:
We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can. |
@@ -72,6 +72,20 @@ app.whenReady().then(() => { | |||
}) | |||
``` | |||
|
|||
You must not use a top-level `await` with the app's `whenReady` promise. Doing so will cause the app to hang. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Potentially also good here to add a rephrased version of the underlying reason:
The ready event is only emitted when the entry point fully resolved, but your entry point is now waiting for the ready event
There are a few other ways to avoid the top-level await, but I wasn't sure if we wanted to demonstrate more than just one option. // Use `then`, which is common in the rest of the docs.
app.whenReady().then(() => {
console.log('Ready')
})
// Use an async function and call it.
async function main() {
await app.whenReady()
console.log('Ready')
}
main()
// Use an async IIFE.
(async () => {
await app.whenReady()
console.log('Ready')
})() Another point that might be worth mentioning is that none of these examples will catch any errors. The following is a more complete example. app.whenReady().then(() => {
console.log('Ready')
}).catch(err => {
console.error(err)
// or maybe `dialog.showErrorBox(...)`
}) |
Description of Change
Using a top-level
await
with an app'swhenReady
promise will cause the app to hang. This does not seem to be documented on the page that explains the caveats when using ESM. This PR adds a note with a positive and negative example to help users avoid this pitfall.This PR is currently in draft mode since I made the change on GitHub.com and I haven't had the chance to run any lint commands if needed.
See #40719. This PR does not fix that issue, but it does document the current behavior.
Checklist
Release Notes
Notes: Explained that
whenReady
cannot be awaited at the top-level when using ESM.