What is App Manifest in PWA

Nov 7, 2025

Introduction

If you’re diving into Progressive Web Apps (PWAs), you’ve probably heard about the app manifest. But what exactly is it, and why does it matter for your app? The app manifest is a simple JSON file that tells the browser how your PWA should behave when installed on a device. It’s a key part of making your web app feel like a native app.

In this article, I’ll walk you through what an app manifest is, why it’s important, and how it works. You’ll also learn how to create one and what features it supports. By the end, you’ll understand how the app manifest helps your PWA deliver a smooth, app-like experience to users.

What Is an App Manifest in PWA?

An app manifest is a JSON file that provides metadata about your Progressive Web App. Think of it as a blueprint that tells the browser how your app should look and behave when installed on a user’s device. This file is essential for turning your website into a PWA.

Here’s what the app manifest typically includes:

App name and short name: How your app is labeled on the home screen.
Icons: Images used for the app icon on different devices.
Start URL: The page that opens when the app launches.
Display mode: How the app appears (fullscreen, standalone, minimal-ui, or browser).
Theme and background colors: Colors used for the app’s UI and splash screen.
Orientation: Preferred screen orientation (portrait or landscape).

The manifest file is linked in your HTML using a <link rel="manifest" href="manifest.json"> tag. When a user installs your PWA, the browser reads this file to configure the app’s appearance and behavior.

Why Is the App Manifest Important for PWAs?

The app manifest is crucial because it bridges the gap between a website and a native app. Without it, your PWA would just be a regular website in a browser tab. Here’s why the manifest matters:

Enables installation: The manifest allows users to add your PWA to their home screen with a proper app icon.
Controls app appearance: It defines how your app looks when launched, including whether it opens fullscreen or in a browser tab.
Improves user experience: By specifying colors and orientation, it creates a consistent and polished feel.
Supports offline and startup behavior: The start URL and splash screen settings help your app load smoothly.
Boosts engagement: Users are more likely to use and return to an app that feels native and integrated.

In short, the app manifest is what makes your PWA feel like a real app, not just a website.

Key Features of the App Manifest

The app manifest supports several features that enhance your PWA’s usability and appearance. Here are some of the most important:

1. App Name and Short Name

Name: The full name of your app, shown in app stores or installation prompts.
Short name: A shorter version used on the home screen or app launcher to save space.

2. Icons

You can specify multiple icons in different sizes (e.g., 48x48, 96x96, 192x192 pixels).
These icons are used for the home screen, splash screen, and task switcher.
Providing various sizes ensures your app looks sharp on all devices.

3. Start URL

Defines the URL that opens when the user launches the app.
Usually set to your app’s main page or a specific landing page.
Helps control the user’s first experience with the app.

4. Display Modes

The manifest lets you choose how your app displays:

Fullscreen: The app takes up the entire screen, no browser UI.
Standalone: Looks like a native app with minimal browser UI.
Minimal-UI: Shows a minimal browser toolbar.
Browser: Opens in a regular browser tab.

Choosing the right display mode affects how immersive your app feels.

5. Theme and Background Colors

Theme color: Sets the color of the browser’s address bar or app title bar.
Background color: Used for the splash screen while the app loads.

These colors help brand your app and improve visual consistency.

6. Orientation

You can specify if your app prefers portrait or landscape mode.
This is useful for games or media apps that work best in a specific orientation.

How to Create and Use an App Manifest

Creating an app manifest is straightforward. Here’s a step-by-step guide:

Step 1: Create a JSON File

Make a file named manifest.json in your project folder. Here’s a simple example:

{
  "name": "My Awesome PWA",
  "short_name": "AwesomeApp",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0a74da",
  "orientation": "portrait",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Step 2: Link the Manifest in Your HTML

Add this line inside the <head> tag of your HTML file:

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

Step 3: Test Your Manifest

Use tools like Chrome DevTools or Lighthouse to check if your manifest is valid and your PWA meets installation criteria.

Step 4: Add Service Workers

While the manifest controls appearance and installation, service workers handle offline support and caching. Together, they make your PWA powerful.

Common Use Cases for App Manifest in PWAs

The app manifest is used in many scenarios to improve user experience:

E-commerce apps: Allow users to install the store app for quick access.
News apps: Provide offline reading and a native feel.
Social media platforms: Enhance engagement with app-like behavior.
Games: Control orientation and fullscreen display.
Productivity tools: Offer a distraction-free environment with standalone mode.

By customizing the manifest, developers tailor the PWA experience to their audience’s needs.

Troubleshooting Common Manifest Issues

Sometimes, PWAs don’t install or display correctly due to manifest problems. Here are common issues and fixes:

Manifest not found: Ensure the manifest file path is correct and linked properly.
Invalid JSON: Use a JSON validator to check for syntax errors.
Missing icons: Provide icons in recommended sizes (192x192 and 512x512 pixels).
Incorrect start URL: Make sure the start URL is accessible and valid.
Display mode ignored: Some browsers may default to browser mode if the manifest is incomplete.

Regularly testing your manifest with tools like Lighthouse helps catch these problems early.

How Browsers Use the App Manifest

Browsers read the app manifest to decide how to present your PWA when installed. Here’s what happens behind the scenes:

The browser downloads the manifest file when the page loads.
It checks if the app meets installability criteria (valid manifest, service worker, HTTPS).
If eligible, the browser prompts the user to install the app.
Once installed, the browser uses the manifest data to create an app shortcut with the specified icon and name.
When launched, the app opens with the display mode and start URL defined in the manifest.

Different browsers may have slight variations, but the manifest is the standard way to control PWA installation and appearance.

Enhancing Your PWA with Advanced Manifest Features

Beyond the basics, the app manifest supports some advanced options:

Related applications: Link to native apps in app stores.
Prefer related applications: Suggest users install native apps instead of the PWA.
Scope: Define the navigation scope of your app to restrict URLs considered part of the app.
Description: Provide a short description for app stores or install prompts.
Screenshots: Showcase your app’s UI in app stores or install dialogs.

Using these features can improve your app’s discoverability and user trust.

Conclusion

The app manifest is a small but powerful file that transforms your website into a Progressive Web App. It controls how your app looks, how it launches, and how users interact with it on their devices. Without it, your PWA would lack the native feel that users expect.

By understanding and properly configuring the app manifest, you can make your PWA more engaging, installable, and user-friendly. Whether you’re building a simple blog or a complex app, the manifest is a key step toward delivering a seamless app experience.

FAQs

What file format is the app manifest in?

The app manifest is a JSON file, typically named manifest.json. It contains metadata about your PWA in a structured, easy-to-read format.

Can I use any icon size in the manifest?

It’s best to include multiple icon sizes, especially 192x192 and 512x512 pixels, to ensure your app looks good on all devices and platforms.

Does the app manifest handle offline functionality?

No, offline support is managed by service workers. The manifest controls appearance and installation behavior.

How do I test if my app manifest works?

Use browser developer tools like Chrome DevTools or audit your PWA with Lighthouse to check manifest validity and installability.

Is the app manifest required for all PWAs?

While not strictly required, the manifest is essential for enabling installation and providing a native app experience, making it a best practice for all PWAs.

Comments (0)

Discuss on Hashnode