Skip to main content

Angular App Manifest

Introduction​

An App Manifest is a critical component of Progressive Web Applications (PWAs) that enables users to install your Angular application on their devices - making it behave more like a native app. This JSON file provides browsers with important information about your application such as its name, icons, theme colors, and how it should behave when installed.

In this tutorial, you'll learn how Angular PWAs handle manifests, how to customize them, and how they contribute to creating an app-like experience for your users.

Prerequisites​

Before diving into Angular App Manifests, you should have:

  • Basic knowledge of Angular
  • Angular CLI installed
  • Familiarity with JSON format

Understanding the Web App Manifest​

A web app manifest is a simple JSON file that provides metadata about your web application. When properly configured, it enables browsers to:

  • Install your app to the user's home screen
  • Display your app name and icon
  • Control the app's display mode (fullscreen, standalone, etc.)
  • Set the app's theme colors
  • Define a splash screen

Setting Up an Angular PWA with a Manifest​

Let's start by setting up an Angular PWA with a properly configured manifest file.

1. Create a new Angular project​

If you don't have an existing project, create one with the Angular CLI:

bash
ng new my-pwa-app
cd my-pwa-app

2. Add PWA support to your Angular application​

Angular provides the @angular/pwa package that adds PWA support to your application:

bash
ng add @angular/pwa

This command does several important things:

  • Adds the @angular/service-worker package
  • Configures your app to use service workers
  • Creates a default manifest.webmanifest file
  • Updates your angular.json file to include the manifest
  • Generates default icons in various sizes

3. Examine the generated manifest file​

After running the command above, you'll find a new file called manifest.webmanifest in your project's src directory. Here's what a basic manifest looks like:

json
{
  "name": "my-pwa-app",
  "short_name": "my-pwa",
  "theme_color": "#1976d2",
  "background_color": "#fafafa",
  "display": "standalone",
  "scope": "./",
  "start_url": "./",
  "icons": [
    {
      "src": "assets/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png",
      "purpose": "maskable any"
    },
    // More icons...
  ]
}

Key Manifest Properties Explained​

Let's understand what each of these properties does:

Essential Properties​

  • name: The full name of your application as displayed on the install prompt and splash screen
  • short_name: A shorter name used on the home screen when space is limited
  • icons: An array of image objects with different sizes for different device resolutions
  • start_url: The URL that is loaded when the user launches your application
  • display: Controls how the app appears when launched (options: fullscreen, standalone, minimal-ui, browser)

Additional Properties​

  • theme_color: The color of the browser's UI elements when your app is running
  • background_color: The background color of the splash screen displayed while your app loads
  • scope: Defines the navigation scope of your PWA
  • description: A brief description of what your app does
  • orientation: Preferred orientation (portrait or landscape)
  • lang: Primary language of the manifest content

Customizing Your Angular App Manifest​

Now that you understand the basics, let's customize the manifest for your application:

1. Update the basic information​

Open manifest.webmanifest and update the basic information:

json
{
  "name": "My Amazing PWA Application",
  "short_name": "Amazing PWA",
  "description": "An amazing PWA that showcases Angular capabilities",
  "theme_color": "#673ab7",
  "background_color": "#ffffff",
  "display": "standalone",
  "scope": "./",
  "start_url": "./",
  "icons": [
    // Icons will be here
  ]
}

2. Customize the display mode​

The display mode determines how much of the browser UI is shown when the app is launched. Options include:

  • fullscreen: All browser UI elements are hidden
  • standalone: App looks like a native app (most common)
  • minimal-ui: Some browser UI elements remain
  • browser: Regular browser experience

For an app-like experience, standalone is usually the best choice:

json
{
  "display": "standalone"
}

3. Create and update app icons​

For the best experience across devices, you should provide icons in various sizes. The generated icons are placeholders - replace them with your own.

You can create icons using design tools like Adobe XD, Sketch, or online tools like Favicon Generator.

After creating your icons, update the icons array in your manifest:

json
"icons": [
  {
    "src": "assets/icons/icon-72x72.png",
    "sizes": "72x72",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-96x96.png",
    "sizes": "96x96",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-128x128.png",
    "sizes": "128x128",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-144x144.png",
    "sizes": "144x144",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-152x152.png",
    "sizes": "152x152",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-192x192.png", 
    "sizes": "192x192",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-384x384.png",
    "sizes": "384x384",
    "type": "image/png",
    "purpose": "maskable any"
  },
  {
    "src": "assets/icons/icon-512x512.png",
    "sizes": "512x512",
    "type": "image/png",
    "purpose": "maskable any"
  }
]

The purpose attribute defines how the icon should be used:

  • any: The icon is used as-is
  • maskable: The icon can be safely cropped to fit the device's icon shape
  • monochrome: The icon is displayed in a single color

4. Configure orientation and categories​

You can add additional properties to enhance your PWA:

json
{
  "orientation": "any",
  "categories": ["productivity", "utilities"],
  "lang": "en-US",
  "dir": "ltr",
  "prefer_related_applications": false
}

Verifying Your Manifest​

To ensure your manifest is correctly set up:

  1. Build your application in production mode:
bash
ng build --prod
  1. Serve your built app using an HTTP server:
bash
npx http-server -p 8080 -c-1 dist/my-pwa-app
  1. Open Chrome DevTools and navigate to the "Application" tab
  2. Select "Manifest" to view the parsed manifest and check for errors

Real-World Example: Creating a Weather PWA​

Let's apply what we've learned to create a manifest for a weather PWA:

json
{
  "name": "WeatherNow - Real-Time Weather Updates",
  "short_name": "WeatherNow",
  "description": "Get accurate weather forecasts and real-time updates for your location",
  "theme_color": "#3498db",
  "background_color": "#ecf0f1",
  "display": "standalone",
  "orientation": "any",
  "scope": "./",
  "start_url": "./",
  "icons": [
    {
      "src": "assets/weather-icons/sunny-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/weather-icons/sunny-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
    // Additional icons...
  ],
  "shortcuts": [
    {
      "name": "View Forecast",
      "short_name": "Forecast",
      "description": "View the 7-day forecast",
      "url": "/forecast",
      "icons": [{ "src": "assets/icons/forecast.png", "sizes": "192x192" }]
    },
    {
      "name": "View Radar",
      "short_name": "Radar",
      "description": "See the precipitation radar",
      "url": "/radar",
      "icons": [{ "src": "assets/icons/radar.png", "sizes": "192x192" }]
    }
  ],
  "screenshots": [
    {
      "src": "assets/screenshots/weather-home-narrow.jpg",
      "sizes": "320x640",
      "type": "image/jpeg",
      "form_factor": "narrow"
    },
    {
      "src": "assets/screenshots/weather-home-wide.jpg",
      "sizes": "1024x768",
      "type": "image/jpeg",
      "form_factor": "wide"
    }
  ]
}

This example includes advanced features:

  1. Shortcuts: Quick actions that appear in the context menu when a user right-clicks on the app icon
  2. Screenshots: Images that show the app in action, displayed in the install prompt

Understanding the Angular Integration​

When you use the @angular/pwa schematic, Angular updates your application to include the manifest:

  1. The index.html file gets a link to the manifest:
html
<link rel="manifest" href="manifest.webmanifest">
  1. The angular.json file is updated to include the manifest in the assets:
json
"assets": [
  "src/favicon.ico",
  "src/assets",
  "src/manifest.webmanifest"
]
  1. A service worker configuration file ngsw-config.json is created:
json
{
  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "app",
      "installMode": "prefetch",
      "resources": {
        "files": [
          "/favicon.ico",
          "/index.html",
          "/manifest.webmanifest",
          "/*.css",
          "/*.js"
        ]
      }
    },
    // Other asset groups...
  ]
}

Testing the Install Experience​

To test the full PWA installation experience:

  1. Deploy your application to a web server with HTTPS
  2. Open the application in a modern browser like Chrome
  3. Look for the installation prompt in the address bar or menu
  4. Alternatively, manually trigger installation via the browser menu

You can use services like Netlify, Vercel, or Firebase Hosting for simple HTTPS deployment.

Troubleshooting Common Issues​

Manifest not being detected​

Check that:

  • The manifest file is properly referenced in your index.html
  • The file is included in the build output (check angular.json)
  • Your server is returning the correct MIME type (application/manifest+json)

Icons not appearing​

Ensure that:

  • The icon paths are correct (relative to the root of your deployed app)
  • The icons exist at the specified locations
  • The images are in the correct format (usually PNG)

PWA not installable​

For a PWA to be installable, you need:

  • A valid manifest with all required fields
  • A registered service worker
  • The app served over HTTPS
  • At least one 192x192 pixel icon
  • A name or short_name
  • A valid start_url

Summary​

The App Manifest is a crucial part of any Angular PWA, providing the metadata browsers need to present your application as an installable app. By properly configuring your manifest, you can control how your app appears and behaves when installed on a user's device.

In this guide, you've learned:

  • What a web app manifest is and why it's important
  • How to set up an Angular PWA with a manifest
  • The key properties of a manifest file
  • How to customize your app's appearance and behavior
  • How to test and troubleshoot your manifest

With these skills, you can create Angular PWAs that offer a truly app-like experience for your users, with the benefits of web delivery and discoverability.

Additional Resources​

Exercises​

  1. Create a custom manifest for a todo list PWA with a purple theme color
  2. Add shortcuts to your manifest that provide quick links to important areas of your app
  3. Create a set of custom icons for your application in all the recommended sizes
  4. Use the Lighthouse tool in Chrome DevTools to audit your PWA and fix any manifest-related issues
  5. Implement a dynamic manifest that changes theme colors based on user preferences

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)