The Launch Handler API is a web platform feature that gives Progressive Web Apps (PWAs) control over how they launch when a user clicks a link pointing to the app's scope. By default, browsers may open a new window every time, leading to multiple duplicate instances. With Launch Handler, you can specify whether to focus an existing window, navigate within it, or always open a new one. This dramatically improves user experience by preventing window clutter and maintaining app state. Configure it via the launch_handler field in your manifest.json.

• auto — The browser chooses the behavior (typically navigates existing window if available). This is the default.
• focus-existing — If an app window is already open, bring it into focus without navigating to a new URL. The existing window's content remains unchanged. If no window exists, a new one opens.
• navigate-new — Always opens a new app window and navigates to the target URL, even if another window exists.
• navigate-existing — If an app window exists, navigates that window to the new URL. If multiple exist, the most recently focused one is used. If none exist, a new window opens.

You can also specify an array like ["focus-existing", "navigate-new"] for fallback behavior.

Add the launch_handler field to your manifest.json:

{
  "name": "My App",
  "start_url": "/",
  "display": "standalone",
  "launch_handler": {
    "client_mode": "focus-existing"
  }
}

For advanced routing (Chrome 110+), use route_to with pathname patterns. Use the configuration generator above to build your manifest interactively.

Currently, Chromium-based browsers (Chrome 98+, Edge 98+, Opera 84+) support Launch Handler API. Firefox and Safari do not support it. For unsupported browsers, the launch_handler field is simply ignored, and the browser falls back to its default launch behavior. This makes it safe to include as a progressive enhancement. Check the compatibility table above for detailed version information.

route_to (available in Chrome 110+) allows you to define URL-path-based rules for different launch behaviors. Each rule has a pathname pattern (using simple glob matching with *) and a corresponding client_mode. Optionally, you can specify a target_url to redirect the launch to a different URL.

Example pattern: /play/* matches /play/song/123 but not /playlist. The * wildcard matches any sequence of characters within a path segment.

No. The Launch Handler API only works with installed PWAs (apps added to the home screen or desktop via the browser's install prompt). Regular browser tabs do not respond to launch_handler configurations. The app must have a valid manifest with display set to standalone, fullscreen, or minimal-ui and be installed by the user.

1. Serve your PWA over HTTPS (or localhost).
2. Open Chrome and navigate to your app.
3. Click the install icon in the address bar to install the PWA.
4. Close all PWA windows.
5. Click an external link that points to your app's scope (or use chrome://launch-handler internal testing).
6. Observe the launch behavior based on your client_mode setting.
7. Use Chrome DevTools → Application → Manifest to verify your manifest is loaded correctly.

Yes, they work together. The scope in your manifest defines which URLs are considered "within" your PWA. Launch Handler only applies to URLs that fall inside your app's scope. If a user clicks a link outside your scope, the browser handles it normally. Ensure your scope is correctly set (defaults to the directory of start_url) for Launch Handler to work as expected.