manifest.json Application Configuration

The manifest.json file serves as the central configuration hub for web applications, progressive web apps (PWAs), and br

The manifest.json file serves as the central configuration hub for web applications, progressive web apps (PWAs), and browser extensions. As a JSON-formatted metadata file, it declares essential information to the browser or operating system—such as the application name, icons, launch behavior, required permissions, and visual theming. While originally standardized for PWAs, the manifest format has been adopted across diverse environments, including Chrome and Edge extensions, Android web apps, and emerging fast-app frameworks. Proper configuration directly influences whether a web app can be installed on a user’s home screen, how it appears in the app switcher, and whether it behaves like a native experience or a standard browser tab.

A manifest is typically referenced from the HTML document’s <head> section:

<link rel="manifest" href="/manifest.json">

The serving server should configure the Content-Type header as application/manifest+json or application/json. For PWA deployment, a secure context is required—this means HTTPS in production or localhost during development. Without a secure context, many installable features, such as service worker registration and home-screen addition, are disabled or restricted.

Core Configuration Fields

At its heart, a PWA manifest contains a defined set of fields that the browser reads to construct the installation UI, address bar theming, and startup behavior. While implementations may extend the schema, the following core fields are widely supported:

  • name: The full, human-readable name of the application. This string appears beneath the icon on the home screen, in the app switcher, and within the install prompt. Clarity and conciseness are recommended.
  • short_name: A abbreviated version of the name, typically used when real estate is limited, such as under a launcher icon or in a constrained system UI. If omitted, the browser may truncate or fallback to name.
  • start_url: The URL that the browser loads when the user launches the installed app. This should ideally point to the app’s entry point and may include query parameters (e.g., ?source=pwa) for analytics or routing purposes. It is best practice to keep start_url within the same origin as the serving page.
  • scope: Defines the set of URLs that the browser considers to be within the application’s boundaries. If the user navigates outside this scope, the browser typically reverts to standard web browsing behavior. Keeping start_url and scope within the same origin prevents unexpected navigation anomalies.
  • display: Controls the visual frame of the launched application. Accepted values include fullscreen, standalone, minimal-ui, and browser. standalone is the most common choice for PWAs, as it hides the address bar and presents the app in a chrome-less window that mimics a native application.
  • theme_color: Hints the browser for theming the address bar, task switcher, or system status bar. Setting this to a brand-aligned hex value enhances visual consistency and gives the impression of a polished, integrated experience.
  • background_color: Specifies the background color of the splash screen displayed during app launch, before the page’s onload event fires. Providing this value prevents layout shift and offers a smoother visual transition.
  • description: A brief summary of the app’s functionality. While not all browsers render this in the install prompt, it may be used by search engines or app stores.
  • lang and dir: The lang attribute (e.g., en-US, zh-CN) declares the primary language of the app’s content, aiding screen readers and localization tools. The dir attribute (ltr for left-to-right, rtl for right-to-left) controls text directionality for languages that require it.
  • id: An optional but recommended unique identifier for the application. Explicitly setting id ensures that the app’s identity remains stable across updates, especially when start_url parameters change. Without it, the browser may treat modified URLs as distinct applications.

These fields form the foundation of a functional manifest. Omitting non-critical values is permissible, but providing at minimum name, short_name, start_url, display, and a set of icons ensures the best chance of a successful install prompt.

Icons and Splash Screens

Visual assets are among the most impactful elements of a manifest. Icons serve as the primary identifier on the home screen, in search results, and within the operating system’s app launcher. A well-curated icon set adapts to various device resolutions, color themes, and shape masks.

Modern browsers and platforms expect at least two primary icon sizes:

  • 192x192: Standard icon for the home screen and task switcher.
  • 512x512: High-resolution icon, often used for the splash screen or by platforms that scale down from this source.

The purpose attribute fine-tunes how an icon is rendered, particularly on systems that support adaptive icons:

  • any: A conventional icon suitable for general use.
  • maskable: Designed for adaptive icon systems. The icon should keep critical content within a safe inner area (typically a circle or square inset), as the system will apply its own shape mask. This is strongly recommended for Android and modern desktop PWAs.
  • monochrome: A single-color icon intended for dark mode or system themes that invert or tint icons based on the current color scheme.

In addition to icons, the screenshots array can enhance the install prompt by showing representative content from the app. Each screenshot entry includes src, sizes, type, and an optional form_factor (e.g., wide or narrow). Providing high-quality, landscape-oriented screenshots gives users a preview of the app’s interface, potentially increasing conversion rates from prompt to install.

Shortcuts and Advanced Capabilities

Beyond the basic launch experience, manifests can expose quick-action shortcuts that appear when a user long-presses or right-clicks the app icon. The shortcuts array allows developers to define context-specific entries that open specific sections or tasks within the app:

"shortcuts": [
  {
    "name": "New Task",
    "short_name": "New",
    "url": "/new?source=shortcut",
    "icons": [{ "src": "/icons/new.png", "sizes": "96x96" }]
  }
]

Each shortcut may include a name, a shorter display label, a target URL, and optional icons. These shortcuts deepen engagement by reducing the number of taps needed to reach key functionality.

The manifest also supports a suite of advanced fields that integrate the web app more tightly with the host platform:

  • share_target: Registers the app as a valid destination for system share sheets. When a user shares a link or file from another application, the configured share_target appears as an option, enabling the web app to receive and process the shared data.
  • protocol_handlers: Declares custom URL schemes (e.g., myapp://) that the app can handle. If a user clicks a link using such a scheme, the browser may prompt to open it with the registered web app.
  • file_handlers: Similar to protocol handlers, but specifically for file types (e.g., image/*, pdf). The app can declare itself capable of opening specific MIME types, allowing users to select it from a “Open With” menu.
  • launch_handler: Provides granular control over how the app launches on subsequent invocations. It can specify whether a new window should be created, an existing window reused, or a new tab instantiated.
  • display_override: An array of display modes ordered by preference. The browser selects the first supported mode, allowing developers to express a preference for standalone while gracefully falling back to browser on unsupported platforms.

These capabilities transform manifest.json from a simple styling sheet into a functional manifest that can influence system-level behavior, inter-app communication, and user workflows.

manifest.json in Browser Extensions

While the PWA manifest focuses on installation and user experience, the same filename is used in a completely different context: browser extensions. Extensions built for Manifest V3 (MV3) employ a distinct set of fields, and conflating the two manifest types is a common source of configuration errors.

A typical MV3 manifest looks like this:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "action": { "default_popup": "popup.html" },
  "permissions": ["storage"],
  "background": { "service_worker": "background.js" }
}

Key differences from the PWA manifest include the mandatory manifest_version field, the use of version for extension identity, and the action field (which replaced the older browser_action and page_action). Extension manifests also rely heavily on permissions, content_scripts, options_page, and commands. It is crucial to understand that PWA and extension manifests serve non-overlapping purposes; a file intended for one should not be used for the other, and platform stores will validate and reject mismatched schemas.

Debugging and Validation

Once a manifest is in place, verifying its correct parsing and behavior is essential. Modern browser developer tools provide dedicated inspection paths:

  • In Chromium-based browsers, navigate to Application > Manifest within DevTools. This panel displays the resolved manifest, highlights any parsing errors, and shows which fields are being used for the install prompt.
  • Lighthouse audits, particularly the “Progressive Web App” category, will report on manifest completeness, icon validity, and compliance with installability criteria.
  • JSON syntax must be strict: no trailing commas, no unescaped control characters, and proper quoting of all string values. A single syntax error will prevent the browser from reading the file entirely.
  • Image paths are resolved relative to the document’s origin. Verify that icon and screenshot URLs are accessible, that the MIME type served is image/png (or image/svg+xml for vector icons), and that the files are not blocked by CORS or authentication redirects.
  • After modifying the manifest, a hard refresh (often Cmd/Ctrl + Shift + R) may not be sufficient. In some cases, clearing the browser’s application cache or updating the service worker is necessary to reflect changes, especially if the manifest influences the service worker scope or lifecycle.

Best Practices

To maximize the effectiveness of a manifest.json configuration and ensure a consistent experience across devices and browsers, consider the following guidelines:

  • Keep names concise: Aim for short_name to be 12 characters or fewer. This prevents truncation and maintains readability across different screen sizes and languages.
  • Maintain origin consistency: Align start_url and scope to the same origin. Crossing origins can cause the browser to treat the app as a external website, breaking the install prompt and navigation expectations.
  • Provide maskable icons: Include at least one icon with purpose: "maskable". This future-proofs the app against adaptive icon systems on Android, Wear OS, and modern desktop environments.
  • Align theme colors with branding: Set theme_color and background_color to values that match your visual identity. Consistent theming reduces the feeling of “jumping” between the web and native contexts.
  • Avoid embedding secrets: Never place API keys, authentication tokens, or sensitive paths inside the manifest. The file is publicly downloadable and readable by any user or script.
  • Use id for stability: If your app undergoes URL restructuring or parameter