Develop

Get started with PWA packaging

Updated: Jul 22, 2026

Overview

Before packaging a web app for Meta Quest, publish a standards-based Web App Manifest and test the hosted experience in Meta Quest Browser. The same preparation applies to 2D sites, screen-based 3D sites, and immersive WebXR experiences.

Before you begin

Host the web app and its manifest over HTTPS. Choose a start page that opens the app experience, and make sure its assets are available from the hosted site.

Create a web app manifest

Create a manifest.webmanifest file. The following example uses fields defined by the Web App Manifest standard⁠:

{
  "name": "Example web app",
  "short_name": "Example",
  "start_url": "https://example.com/startpage/",
  "scope": "https://example.com/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "icons": [
    {
      "src": "/images/icon-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icon-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ]
}

Replace the example names, URLs, colors, and icon paths with values for your app. Keep start_url within scope.

Open the manifest URL directly and confirm that the server returns valid JSON.

Manifest fields used by Bubblewrap

@meta-quest/bubblewrap-core version 1.24.1 reads the following fields when it creates the Android project. This is a field reference, not a list of mandatory and optional fields.

Field	How Bubblewrap uses it
`name`, `short_name`	Set the generated application name and launcher label. If one is absent, Bubblewrap derives a value from the other.
`start_url`	Resolves against the manifest URL and becomes the package launch path.
`scope`	Resolves against the manifest URL and defines the URL boundary for the app. Keep `start_url` within this boundary.
`icons`	Supplies launcher and splash imagery. Bubblewrap selects suitable `any`, `maskable`, and `monochrome` icons and uses a 512-pixel-or-larger app icon when available.
`display`	Sets the Trusted Web Activity display mode. During Meta Quest initialization, the CLI prompts for this value for a `2D` package and uses `standalone` for an `immersive` package.
`theme_color`, `background_color`	Set the generated project theme color and splash screen background.
`theme_color_dark`	Sets the dark theme color. This Bubblewrap extension defaults to `#000000` when it is absent.
`additional_trusted_origins`	Adds other HTTPS hosts to the generated Trusted Web Activity configuration. This Bubblewrap extension is used for multi-origin 2D apps.

The Web App Manifest standard defines additional fields. Bubblewrap can package a manifest that contains fields beyond this reference.

An in-scope URL stays in the packaged experience. An out-of-scope URL is no longer treated as trusted app content.

In a 2D package, an out-of-scope link opened in the same browsing context stays in the panel and displays custom tab UI. A link that opens a new tab or window opens in Meta Quest Browser. In an immersive package, an out-of-scope link opens in Meta Quest Browser.

For a 2D app that uses more than one origin, add each additional origin to additional_trusted_origins. Publish a matching Digital Asset Links file on the primary origin and every additional trusted origin. See multi-origin support.

Test the hosted app

Open the start URL in Meta Quest Browser and test the app’s primary flow. Use remote debugging to inspect the page from your development computer.

For screen-based 3D, test the site as windowed Browser content. For immersive content, confirm that the WebXR experience starts in Browser before packaging it. See the WebXR overview for the immersive workflow.