docs: explain avoiding top-level await with whenReady

[jordanbtucker]

Description of Change

Using a top-level await with an app's whenReady 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

• PR description included and stakeholders cc'd
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Explained that whenReady cannot be awaited at the top-level when using ESM.

[welcome]

💖 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:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

Things that will help get your PR across the finish line:

• Follow the JavaScript, C++, and Python coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made following the documentation styleguide.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

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.

[codebytere]

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

[jordanbtucker]

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(...)`
})