Manifest scope: your PWA's installation boundary
In one line: scope is the fenced boundary of your installed app. URLs inside it
open in the app-like window (no address bar); URLs outside it re-expose browser
chrome to signal the user has left the app. share_target and shortcuts only work
inside scope, and start_url must sit within it.
Why scope matters
Section titled “Why scope matters”- Shared links. A link that lands in-scope keeps the app-like interface and hides the URL bar. Out-of-scope, browsers re-expose the URL bar — “you’re on a different page of this site” — which weakens the installed experience.
- Multiple installed apps. Products that ship separate apps (e.g. an Admin PWA vs a Customer PWA) hit N+1 install friction when scopes across manifests conflict.
- Scoped capabilities.
share_targetandshortcutsonly function for URLs inside the app scope.
In-scope vs out-of-scope
Section titled “In-scope vs out-of-scope”- In-scope paths begin with the scope string (
/app/matches/app/,/app/page.html,/app/dashboard/). Browser controls are suppressed. - Out-of-scope paths (
/,/blog/when scope is/app/) show the URL bar again. - Scope does not block navigation off-scope — it changes presentation, not access.
Browser & ecosystem support
Section titled “Browser & ecosystem support”| Browser / Platform | Support | Since | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Android) | ✅ yes | 73 | high | ref | — |
| Chrome (Desktop) | ✅ yes | 73 | high | ref | — |
| Edge (Desktop) | ✅ yes | 79 | high | ref | — |
| Safari (iOS) | ✅ yes | 16.4 | medium | ref | Honored for home-screen web apps; off-scope navigation surfaces a banner rather than a full address bar. |
| Safari (macOS) | ✅ yes | 17 | medium | ref | Applies to Dock-installed web apps. |
| Firefox (Desktop) | ❌ no | — | high | ref | No manifest-based install path, so scope is not applied. |
| Samsung Internet | ✅ yes | 6.2 | high | ref | — |
Ecosystem & commercial policy
| Entity | Type | Context | Status | Sponsored | Notes |
|---|---|---|---|---|---|
| Google Play (TWA) | distribution_channel | Google Play TWA | ✅ supported | No | assetlinks.json origin must match the manifest scope origin, or the TWA degrades to a Custom Tab with browser chrome. |
| Microsoft Store (PWA) | distribution_channel | Microsoft Store | ✅ supported | No | Scope defines the in-app boundary store reviewers preview at submission. |
Decision framework
Section titled “Decision framework”| Decision question | Recommended action | Rationale |
|---|---|---|
| Want one unified PWA covering the whole site? | Omit scope (implicit default) or set it to /. |
Reduces N+1 install risk; deep links anywhere go in-app. |
| Need multiple PWAs per section (admin vs customer)? | Use a distinct scope per manifest; keep each start_url inside its scope. |
Each install targets a separate app context; a user can install both. |
Use share_target or shortcuts for key actions? |
Declare scope and verify all target/shortcut URLs are in-scope. |
These features are scoped to the manifest; off-scope URLs won’t trigger for the installed app. |
| Have marketing/blog pages outside the core app? | Set scope to the core-app path (/app/); keep marketing off-scope with clear “return to app” navigation. |
Users still reach the app from distinct entry points and expect the URL bar on marketing content. |
| Is deep-linking a primary flow? | Align scope with the deepest common prefix of deep-linkable paths. | Guarantees in-app presentation for deep links; avoids the “bar reappearing” UX. |
Practical checklist
Section titled “Practical checklist”- Choose one unified PWA (no scope or
/) vs section-specific (explicit/app/). - If you declare a
scope, end it with/so/prefixdoesn’t also match/prefix-of/. - Verify
start_urlis a subpath ofscope— otherwise the browser falls back to astart_url-derived scope and ignores yours. - Ensure every
share_targetURL and everyshortcuts.urlis in-scope. - Test shared deep links while installed: confirm the address bar stays hidden in-scope.
- For multiple PWAs, give each manifest a unique scope and a distinct in-scope
start_url.
What this means for trust
Section titled “What this means for trust”A correctly scoped manifest makes deep links feel native and keeps share and shortcuts reliably in-app. Seeing the familiar app-like interface (no address bar) confirms “this link belongs to my installed app,” reinforcing trust. A clear, stable scope also helps store reviewers validate your PWA’s identity: the scope defines the in-app boundary they preview at submission.