The manifest scope sets your PWA' s installation boundary

Why this matters now:

• Users send and open links to your app (social media, email, chat). If a link lands in-scope, the browser preserves the app-like interface and keeps the URL bar hidden. If it lands out-of-scope, browsers re-expose the URL bar to signal “you’re on a different page of this site,” which can hurt the installed-app experience.
• Some products need multiple installed apps for different sections (e.g., a “Admin PWA” vs “Customer PWA”). Conflicting scopes across manifests cause N+1 install friction: the browser may prompt a second install or degrade installability.
• Features like share_target and shortcuts only work for URLs inside the app scope.

How scope affects the installed experience:

In-scope vs out-of-scope

• In-scope paths begin with the scope string (e.g., /app/ matches /app/, /app/page.html, /app/dashboard/). Browsers suppress browser controls.
• Out-of-scope paths (e.g., /, /blog/ when scope is /app/) show the URL bar (or handle) again, so users see they left the “app part” of the site.
• Scope doesn’t block navigation to out-of-scope URLs; browsers allow off-scope visits in the same context, but change the presentation.

Deep links

• If a deep link is shared (e.g., https://example.com/app/order/123) and /app/ is your scope, installed users open the link in-app without the address bar.
• If the deep link is https://example.com/blog and /app/ is your scope, installed users see the URL bar appear because they navigated off-scope.

Scoped features bound to scope

• share_target: Encodes target URLs that must be in-scope for the manifest that registers them. Out-of-scope share target URLs won’t be used for installed invocation.
• shortcuts: All shortcut URLs must live inside the scope defined in the same manifest. If any shortcut URL falls outside, the browser may ignore that shortcut or refuse to load the manifest.

Decision framework for choosing or omitting scope

| Decision question | Recommended action | Rationale | |-------------------|-------------------|-----------| | Do you want one unified PWA covering the whole site? | Omit scope in the manifest (implicit default) or set it to the origin’s root path (/). | Reduces N+1 install risk; deep links anywhere go “in-app”. | | Do you need multiple PWAs per product/section/admin vs customer? | Use distinct scopes per manifest; ensure the start_url for each is within its declared scope. | Each install targets a separate “app context”; a user can install both. | | Do you use share_target or shortcuts for key actions? | Include scope and verify all target URLs and shortcut URLs are in-scope. | These features are scoped to the app’s manifest; out-of-scope URLs won’t trigger correctly for the installed app. | | Does your site use global marketing or blog pages that don’t belong in the core app? | Set scope to the core-app path (e.g., /app/) and keep marketing in out-of-scope paths; add clear navigation indicators to return to the in-app area. | Users can still reach the app from visibly distinct entry points and expect the URL bar to be shown for marketing content. | | Do you support URL-based state or deep-linking as a primary user flow? | Align scope with the deepest common prefix of deep-linkable paths, and verify deep links land in-scope. | Guarantees in-app presentation for deep links; reduces “bar reappearing” UX. |

Practical checklist

• [ ] Decide between one unified PWA (no scope or /) vs section-specific PWA (use explicit scope like /app/).
• [ ] In the manifest, if you declare a scope (e.g., /app/ or https://example.com/app/), ensure it ends with / to avoid prefix-matching unintended paths (e.g., /prefix also matches /prefix-of/).
• [ ] Verify that start_url is a subpath of scope. If start_url is outside scope, browsers will compute the fallback scope based on start_url, ignoring your declared scope.
• [ ] Ensure all share_target URLs and all shortcuts.url values are in-scope.
• [ ] Test deep links from share and social interactions: open them while the PWA is installed, confirm address bar remains hidden for in-scope URLs.
• [ ] If you need multiple PWAs (e.g., Admin vs Customer), ensure each manifest has a unique scope and a distinct start_url within that scope, and don’t share the same manifest to avoid registration conflicts.
• [ ] Use JSON validation on the manifest; invalid scope types or malformed URLs fall back to default behavior (derived from start_url).

Developer checklist

• [ ] Add "scope" to manifest only when you need a boundary; otherwise, omit it to rely on start_url-based fallback.
• [ ] Prefer absolute or same-origin URLs when setting scope; if using relative URLs, resolve them relative to the manifest’s own path.
• [ ] In your CI/CD, include a manifest-lint step that checks: scope ends with / and start_url is a subpath of scope.
• [ ] For each share_target entry in manifest, check that the target URL begins with scope (or equals start_url if you want a single-activity share entry).
• [ ] For each shortcuts entry, verify the url is within scope.
• [ ] If you introduce new deep-linkable paths, update the scope or add a new manifest for a separate PWA; don’t try to reuse the same manifest for disjointed product sections.
• [ ] Log or instrument “off-scope navigations” in client telemetry to spot discovery or feature gaps (e.g., users frequently open out-of-scope links).

What to avoid

• Don’t set scope to a value that doesn’t include start_url. Browsers will ignore the scope and use the fallback.
• Don’t rely on an ambiguous, non-terminating scope like /prefix without the trailing /, or you may match unintended paths (e.g., /prefix-of/index.html).
• Don’t mix distinct “apps” (Admin vs Customer) under the same manifest just to reduce configs; it creates installability confusion and N+1 install prompts.
• Don’t claim “universal in-app” behavior while hosting support/marketing pages outside your declared scope; deep links will show the URL bar.
• Don’t use dark-pattern prompts to force installs on out-of-scope pages; browsers may still require explicit user actions and users’ trust will erode.

What this means for installability and trust

A correctly scoped manifest makes deep links feel native and keeps share and shortcuts reliably in-app. When users share or click an app link from social media or email, seeing the familiar app-like interface (without the address bar) confirms that “this link belongs to my installed app,” reinforcing trust. Conversely, mismatched scopes or missing scopes where share targets and shortcuts expect them cause these features to “fall back” to a browser-web experience, which feels inconsistent and less integrated.

Providing a clear, stable scope also helps marketplace reviewers and app stores validate your PWA’s identity and boundaries. When you file your manifest with a marketplace, the scope defines what they “preview” as the installed-app boundary; alignment between scope, shortcuts, and share_target makes your app easier to explain and more trustworthy to reviewers and users alike.

Next steps

• Run a scope-audit script (e.g., a tiny JSON schema or lint that checks scope includes start_url and ends with “/”).
• Validate that all share_target URLs and shortcuts.url are within scope.
• Add a smoke test for deep links: use installed PWA; open an in-scope deep link; confirm URL bar stays hidden.
• If you plan multiple PWAs per product, create separate manifests with distinct scopes and unique start_urls; avoid a single manifest claiming multiple sections that behave like different apps.
• Document any intentional off-scope paths in your developer guide so future contributors understand the product’s app boundaries.
• Revise marketplace listings (e.g., screenshots) to highlight scoped features (shortcuts, share actions), reinforcing that they work in-app under the same scope the marketplace validates.