Proposal: `runtime.isFirstInstalled`

[Jack-Works]

Motivation

Now we can use chrome.runtime.onInstalled.addListener, but it has some inconvenience.

If the event listener is not attached in the first event loop, it will miss the event.

Proposal

• browser.runtime.isFirstInstalled: boolean (OnInstalledReason = install)
• browser.runtime.updatedFrom: string | undefined (OnInstalledReason = update)

With these new properties, the extension will less likely to miss the onInstalled event.

[dotproto]

Why can't you register this listener on the first turn off the event loop?

Govern that you've shared so far, it should be possible to address your use case with a userland solution. I believe you can accomplish what your after by simply registering a listener and storing the install reason for later use by adding a the following snippet to your worker:

let install reason = null;
browser.runtime.onInstalled.addListener(reason => installReason = reason);

Then at some point after worker startup you can check installReason and handle the install notification as you please.

[Jack-Works]

Why can't you register this listener on the first turn off the event loop?

Yes, it's possible, but it's easy to introduce a bug to the code that the register does not run on the first event loop.

Our production has had this bug before. We're using Webpack to bundle our code, and we enabled AsyncWebAssembly feature and TopLevelAwait. It accidentally causes our register to miss the install event and that is hard to find the bug.

I think API I proposed can improve the DX.

[tophf]

Top-level await doesn't work in service worker context in Chrome (intentionally), so you won't miss this event due to asynchronicity, but you can still miss it due to a bug in Chrome: onInstalled won't fire on update if the extension was updated while it was disabled and then enabled some time later.

[Jack-Works]

Oh, I mean the Top Level Await that compiled by webpack. Anyway, there're many ways to miss the event but it's not necessary.

[bershanskiy]

you can still miss it due to a bug in Chrome: onInstalled won't fire on update if the extension was updated while it was disabled and then enabled some time later.

This is clearly a Chrome bug and should not require a new API.

Oh, I mean the Top Level Await that compiled by webpack.

Bundlers that use asynchronous module loading can mess up event registrations in lots of different ways. The easiest way to avoid bundle races is to just extract inherently racy logic out of the bundle and just prepend it to the background script.

[rdcronin]

2026 London F2F Triage

Discussed this today. We're unlikely to make this change.

We understand that there can be friction** around registering listeners in the first spin of the event loop; however, this is currently a fundamental requirement for service workers and non-persistent background contexts in general. We agreed it didn't make sense to add a special boolean for this specific case.

** We're also working on making those better, e.g. PR 793 and exploring ways of allowing async event listener registration.