Manifest launch_handler: controlling how an installed app launches

In one line: launch_handler defines a client_mode that tells the browser whether launching an installed app should focus or navigate an existing app window, or open the app in a new one.

Syntax

{
  "launch_handler": {
    "client_mode": "focus-existing"
  }
}

client_mode also accepts an array of strings; the first valid value in the array is used:

{
  "launch_handler": {
    "client_mode": ["focus-existing", "auto"]
  }
}

client_mode values

Value	Meaning
auto	The user agent decides the loading context appropriate for the platform (for example, navigate-existing may make more sense on mobile, and navigate-new on desktop). This is also the default used if all provided values are invalid.
focus-existing	If the app is already loaded in a web app client, that instance is brought into focus but not navigated to the launch target URL. The target URL is made available via Window.launchQueue for custom navigation handling.
navigate-existing	If the app is already loaded, the existing client is brought into focus and navigated to the launch target URL. The target URL is also exposed via Window.launchQueue.
navigate-new	The app is loaded inside a new web app client instance. The target URL is made available via Window.launchQueue.

Fallback behavior

• If a client_mode string (or every value in an array of strings) is invalid, the behavior falls back to auto.
• Both focus-existing and navigate-existing fall back to navigate-new behavior when no existing app instance is currently loaded.

Browser support

launch_handler is marked experimental and has limited availability — it does not work in some widely-used browsers and is not part of Baseline. Check the current browser compatibility data before relying on it in production.

Practical checklist

• Pick a client_mode (or fallback array) matching how the app should behave when launched while already open.
• Read the target URL from Window.launchQueue in all modes that expose one.
• Feature-detect and verify current browser support before depending on non-auto behavior in production.

Cross-references

• Manifest start_url — another manifest member that influences what URL an installed app opens